桌面与浏览器
把对话、代码、Git 与终端放在同一个工作区。Electron 桌面与浏览器共用同一套页面,工作在运行时所在的主机上执行。

选择运行方式
| 入口 | 适合什么场景 | 提供的能力 |
|---|---|---|
| Electron 桌面 | 日常本机开发 | 完整工作区,以及主进程提供的受控浏览器、受控终端窗口。 |
| 独立 Web | 在浏览器中访问开发机 | 对话、文件、Git 和工作区终端。 |
| 浏览器连接桌面运行时 | 换个窗口或设备继续 | 共用主机上的会话与工作区,以及该运行时已启用的服务。 |
当前发布流程提供 CLI 预构建包。桌面与独立 Web 工作区按下面的源码步骤启动;不要把 mica app-server 当作浏览器 HTTP 服务,它是客户端集成用的 stdio 入口。
启动桌面应用
先获取源码,准备 Git、Bun、Node.js 22+ 与 npm。以下步骤以 macOS / Linux 为例:
# 在 mica-code 仓库根目录开始
bun install
MICA_NO_RC=1 \
MICA_INSTALL_PACKAGE_DIR="$HOME/.local/lib/mica-dev" \
MICA_INSTALL_DIR="$HOME/.local/bin/mica-dev" \
bun run build
cd apps/desktop
npm install
MICA_CLI_PATH="$HOME/.local/bin/mica-dev/mica" npm run devbun run build 会构建并安装 CLI;npm run dev 随后构建 Web 服务并启动 Electron 与 Vite。 以上命令将源码 CLI 安装到独立路径,并通过 MICA_CLI_PATH 启动桌面。未指定安装路径时,构建会更新 ~/.local/lib/mica 与 ~/.local/bin/mica,可能覆盖已有的发布版入口,也可能修改 shell 的 PATH 配置。
npm run build、serve:web 和下方打包命令也会构建并安装 CLI;如需保持隔离,执行这些命令时同样设置MICA_NO_RC、MICA_INSTALL_PACKAGE_DIR 和 MICA_INSTALL_DIR,并在启动运行时时设置MICA_CLI_PATH。
打开 Settings 配置模型,然后选择项目目录。终端与桌面共享 MICA_HOME 下的配置、会话和个人扩展;模型字段见模型与配置。
启动浏览器工作区
首次运行先完成构建。下面的命令只在本机回环地址提供服务:
# 在 mica-code 仓库根目录开始
bun install
cd apps/desktop
npm install
MICA_NO_RC=1 \
MICA_INSTALL_PACKAGE_DIR="$HOME/.local/lib/mica-dev" \
MICA_INSTALL_DIR="$HOME/.local/bin/mica-dev" \
npm run build
MICA_CLI_PATH="$HOME/.local/bin/mica-dev/mica" \
npm run start:web -- --host 127.0.0.1 --port 8787 --no-share打开日志中的地址,通常是 http://127.0.0.1:8787。端口被占用时可能回退到其他端口,请以实际日志为准。
已有构建时,只需在 apps/desktop 中执行最后一行。也可用 npm run serve:web -- --host 127.0.0.1 --port 8787 构建后启动。跨设备连接的方法与访问范围见远程与手机访问。
使用工作区
会话与项目
从 New Session 开始,选择工作目录,在输入区选择模型与角色。历史会话可以搜索、置顶并按项目分组;通过侧栏重新打开即可继续。
输入 @ 引用文件,输入 / 选择 Skill 或 MCP 引用。桌面对话框的斜杠补全用于能力引用;终端专用的 /model、/compact 等命令通过对应面板操作。
文件与 Git
在文件视图打开和编辑代码,在 Git 面板查看工作区、暂存区与基线比较。可按文件暂存、取消暂存或确认后丢弃改动。提交前先检查实际 diff 与验证结果。
终端与执行记录
工作区终端用于运行当前项目的命令。回合日志展示思考与工具执行,点击工具行可以查看参数、输出和错误;后台 shell 与子代理有独立详情。

补充要求与旁问
运行中继续输入可以补充要求;输入框为空时按 Shift+← 撤回尚未发送的消息。双击用户消息可在空闲时编辑并重新执行,之后的对话历史会被截断。
临时追问可以使用 By The Way 抽屉,快捷键为 ⌘/Ctrl+Shift+B。旁问保留独立线程,回答不加入主对话上下文。
会话笔记、能力与插件
顶栏的会话笔记用于保留需求与关键决定。输入区的会话设置可以调整工具、Skills、MCP、定时任务和支持会话覆盖的插件设置。更完整的工作方法见日常开发流程。
构建运行产物
在 apps/desktop 中构建并运行:
npm run build
npm run start生成本机可检查的未压缩应用目录,用 npm run build:unpack。需要安装包时选择对应平台:
npm run build:mac
npm run build:linux
npm run build:win这些命令会先执行构建。安装包受平台工具链与原生依赖约束;仓库提供命令不代表支持在任意系统上交叉打包所有平台。
排查问题
- CLI 行为与源码不一致:回到仓库根目录运行
bun run build更新已安装入口。也可以通过MICA_CLI_PATH指向需要验证的可执行文件。 - 连接到旧服务:确认启动日志中的端口;开发时可用
MICA_DESKTOP_PORT=8899 npm run dev指定独立端口。 - Web 中受控窗口服务不可用:它们依赖 Electron 主进程。Web 工作区内的终端仍属于独立可用的能力。
- 隔离测试与日常数据:为测试实例分别设置
MICA_HOME、MICA_DESKTOP_USER_DATA和独立端口;Electron 还应指定独立的--user-data-dir。
下一步可以连接手机与其他开发机,或按需管理插件与能力。