排错与常见问题

常见问题#

常见故障#

1. 下载后无法打开

   首次启动时 macOS 会要求确认打开来自互联网的应用。右键点击应用并选择一次「打开」即可。如果文件看起来已损坏，请重新下载，并在打开前用 SHA256SUMS 比对。

2. 智能体找不到 git、gh 或 docker

   从程序坞启动的应用不会继承终端的 shell 环境。查看「插件 → 命令行工具」，其中列出 PATH 上有哪些工具以及各自是否已登录。通常这会把「智能体推送失败」明确为「gh 从未登录」。

3. 会话长时间没有输出

   会话会说明原因：静默了多少秒、某个具名工具仍在运行、正在等待模型返回，或者进程仅处于存活状态。已停滞的会话在你发送消息后会继续。如果它不是停滞而是在原地重复，几乎总是因为目标不够明确，此时应中断它并重新说明完成标准。

4. 截图或屏幕分析无法使用

   在 macOS 上这些功能需要「屏幕录制」权限，读取桌面或下载目录还需要「完全磁盘访问」。授权对象是启动 Mirasim 的那个应用。权限页面会逐项引导并支持随时重新检查，因为其中部分权限 macOS 完全不会主动询问。

5. Git 操作被拒绝

   面板会指出你处于哪一种常见的 Git 情形：本地改动会被覆盖、分支已分叉、尚未设置上游、远端更靠前、有一次未完成的合并、凭据被拒。同时给出可以解决的操作，例如先暂存再拉取，或者拉取时执行 rebase。看到该提示时仓库尚未发生任何变化。

6. 两个会话产生了冲突的改动

   如果它们运行在各自的 worktree 中，不会有内容丢失：先合并较好的一份，再把另一份 rebase 到它之上或重新生成。下次请给并行的会话分配互不重叠的部分，或者有意让它们并行尝试同一任务，最后保留一份。

7. worktree 无法删除

   worktree 中仍有未提交的改动时，Git 会拒绝移除。请先提交或丢弃这些改动，然后一并删除会话及其 worktree。

8. 任务进行中额度耗尽

   可以切换当前账号，或者登录中转服务并设置兜底阈值，使下一次长任务不会在同一处中断。通过兜底路径执行的轮次会在对话记录中标注，因此事后可以查明发生了什么。

9. 我打开的文件被改动了

   通常是某个智能体在写入该文件。编辑器会提示并询问是从磁盘重新读取还是保留你的版本，不会无声地丢弃任何一方。要还原该文件的 Git 改动之前，请先保存或关闭正在编辑的版本。

10. ui-cli 无法连接应用

    把它指向一个正在运行的实例：已安装的应用使用 --port 4970，开发版桌面实例使用 --port 4950；也可以不带 --port，为该条命令启动一个用后即弃的私有服务。

11. 某个 MCP 服务的工具始终不出现

    先执行一次探活。握手失败的服务会导致智能体无法完成你交给它的工作，而且过程中不会有明显提示。连接器方面，校验会记录工具数量或错误信息；令牌过期时重新完成 OAuth 授权即可。

12. 定时任务没有执行

    定时任务按该服务端的时钟触发，且需要 Mirasim 处于运行状态；错过的触发会被跳过，不会集中补跑。最短间隔为 10 分钟。请查看该任务的运行历史，需要验证时使用「立即运行」，不必等待。

获取帮助#

咨询、缺陷报告和评测方面的深入讨论，都可以发送到页脚的联系地址，由人工处理。请说明涉及哪个工作区、你让智能体做什么、它实际做了什么；条件允许时，把出错的那一轮导出附上。保留下来的轨迹总是比文字描述更有用。