miao 使用指南
1. miao 能帮你完成什么
Section titled “1. miao 能帮你完成什么”miao 是一个在终端中与你协作的开源 AI 智能体,也提供 HTTP 服务与浏览器界面。它帮助你编写代码、开展调研、管理文件和自动化任务。它把重点放在模型调用周围的工作上:持久化会话、上下文效率、代理协作和可观察的成本。
用它理解仓库、实现改动、排查测试失败,或委派专项调研。连接你偏好的供应商,配置项目工具,并在任务变化时继续补充要求。miao 支持模型选择与 MCP;miao 的运行时建设与可用范围见 产品概览 和 工作流对比。
第一次可以这样提需求:「找到这个错误的原因,做出适当的最小修复,运行相关检查,再解释代码差异。」执行过程中继续补充约束,无需另开对话。
miao 采用 MIT 许可证。本指南描述当前源码,已安装的发行版可能尚未包含部分更新。
2. 安装与升级
Section titled “2. 安装与升级”支持 macOS、Linux 和 Windows。Windows 安装脚本由 CI 验证;Windows 终端里的显示仍在验证中。
# 安装稳定版curl -fsSL https://raw.githubusercontent.com/mttydev/miao/main/install | bash
# 指定版本curl -fsSL https://raw.githubusercontent.com/mttydev/miao/main/install | bash -s -- --version 0.0.1
# 从本地二进制安装./install --binary /path/to/miaoWindows 用 PowerShell 安装脚本(Windows PowerShell 5.1 或 PowerShell 7),装到 ~\.miao\bin 并加入用户 PATH:
irm https://raw.githubusercontent.com/mttydev/miao/main/install.ps1 | iex
# 指定版本$env:MIAO_VERSION = "0.0.33"; irm https://raw.githubusercontent.com/mttydev/miao/main/install.ps1 | iex安装脚本默认会把二进制放到 ~/.miao/bin/miao 并写入 PATH;用 --no-modify-path 可跳过。
当前 Windows 版本没有 Authenticode 签名。发布包是 miao-windows-x64.zip(较旧的 CPU 可用 miao-windows-x64-baseline.zip),内含 miao.exe;也可以从 miao GitHub Releases 手动下载解压。安装脚本本身通常不会触发提示,但直接启动下载得到的 miao.exe 可能出现 SmartScreen 的“Windows 已保护你的电脑”对话框。出现时按共用的 Windows 安全提示说明处理;杀毒软件报出威胁时不要放行。
三个入口(并存,互不干扰)
| 命令 | 是什么 | 数据/配置 | 更新 |
|---|---|---|---|
miao |
稳定版(官方 release 二进制) | channel latest,DB miao.db |
显式 miao upgrade |
miao-dev |
从源码运行,唯一能看到未提交改动的入口 | channel local,DB miao-local.db |
手动 |
miao-preview |
当前 checkout 的编译版(./script/install-local.sh --binary /path/to/prebuilt/miao 安装) |
当前分支为 channel | 不自动更新 |
auth.json、配置、快照在各入口间共享,凭证无需重复登录。
升级 / 卸载
miao upgrade # 升级稳定版miao uninstall # 卸载升级会把 ~/.miao/bin/miao 重新指向一个新的版本目录(~/.miao/bin/.versions/<id>/miao,旧目录保留),不会在后台自动进行,也没有环境变量可以开启或关闭它。已经打开的窗口继续运行原来的构建:页脚显示的是正在运行的那个版本,重开窗口才会切换——从带提示的版本起,状态栏会用 warning 样式写出「X installed · restart to apply」。要确认某个窗口跑的是哪个构建,可以看它的启动时间与绑定的版本目录:
ps -o lstart= -p <pid>lsof -p <pid> | grep '.versions/'3. 快速开始
Section titled “3. 快速开始”# 1. 登录 / 配置 provider(凭据写入共享凭据库)miao auth login <integration> <key> # 或在 TUI 里用 /accounts 完成 OAuth / API key 登录
# 2. 列出可用模型miao models
# 3. 在项目目录启动 TUIcd /path/to/projectmiao将 <provider>/<model> 替换成 miao models 中的条目。典型配置(全局 ~/.config/miao/miao.jsonc 或项目内 .miao/miao.jsonc;.opencode/ 作为读取回退):
{ "$schema": "https://mtty.dev/miao/config.json", "model": "<provider>/<model>", "permission": { "*": "ask" }, "lsp": true, "formatter": true,}4. 配置参考
Section titled “4. 配置参考”配置文件按优先级合并:项目 .miao/ > 全局 ~/.config/miao/ > 管理员层 /etc/miao/(Linux)、/Library/Application Support/miao/(macOS)、%ProgramData%\miao\(Windows)。管理员层只有在该目录真实存在时才生效,且永远不优先于用户或项目里的同名键;MIAO_MANAGED_CONFIG_DIR 可改动它的位置,MIAO_CONFIG 则整体指定配置来源。miao debug config 会打印每个生效键以及它来自哪个文件。主要字段:
| 字段 | 作用 |
|---|---|
model |
默认模型(provider/model) |
default_agent |
默认 agent |
permission |
权限规则(allow / ask / deny,可分级按工具/路径);未匹配默认 ask |
agents |
自定义 agent(模型、系统提示、权限、步数上限) |
lsp |
语言服务器:true 启用全部内置,false 关闭,或按名配置。省略 = 全部禁用 |
formatter |
代码格式化:true 启用内置,或按名配置命令 |
mcp |
MCP 服务器(local stdio / remote streamable-http) |
compaction |
压缩(prune 裁剪旧输出、threshold 触发比例、max_context 每模型窗口、summarize_small 廉价摘要、hot_prefix 热前缀、precise_tokens BPE) |
cache |
ttl_seconds 延长 prompt cache TTL |
budget |
会话预算:cost_usd、tokens、turns、wallclock_ms(花到五分之四告警,达上限停止) |
cost |
budget_usd 同一份会话预算的金额轴;Goal 用 goal.budget 声明自己的预算 |
loop |
自治续跑(见 §5.8) |
shell |
默认 shell |
skills / commands / instructions / references / plugins |
技能、命令、指令、引用、插件 |
watcher / attachments / tool_output / snapshots |
文件监听、附件、工具输出阈值、快照 |
providers |
自定义 provider / 模型(含本币单价 cost) |
engine |
旧版配置里的引擎选择,仅为兼容保留;引擎始终在进程内运行,此项不再改变放置 |
experimental |
实验开关(如 Code Mode) |
本币计价:providers.<id>.models.<m>.cost 用 provider 官方本币单价(如 DeepSeek 的 CNY),成本按配置费率估算并记录为 provider 声明的币种,不做汇率换算;账本按币种分别累计。
引擎:引擎就在 miao 二进制里运行,没有需要单独安装或指定路径的引擎;MIAO_ENGINE_STORAGE 可改写它的存储位置(默认 ~/.local/share/miao-engine/storage),miao doctor 会显示协议、schema 版本与将要打开的数据库。开发构建可用 MIAO_ENGINE_BIN 指定单独构建的引擎。
5. 日常使用
Section titled “5. 日常使用”5.1 TUI 快捷键
Section titled “5.1 TUI 快捷键”默认 leader 键是 ctrl+x,组合执行动作:
| 快捷键 | 动作 |
|---|---|
ctrl+p |
命令面板 |
ctrl+x b |
显示/隐藏右侧边栏(子会话不显示) |
ctrl+x m |
选择模型 |
ctrl+x l |
会话列表 |
ctrl+x n |
新建会话 |
ctrl+x t |
主题 |
ctrl+x c |
压缩会话 |
ctrl+x g |
时间线 |
ctrl+x q |
退出 |
prompt 获得焦点时:
| 按键 | 动作 |
|---|---|
shift+← shift+→ shift+↑ shift+↓ |
选中文本(shift+Home/End、shift+ctrl+←/→ 按词) |
alt+a |
全选草稿 |
alt+z / alt+. |
在草稿内撤销 / 重做 |
ctrl+y |
复制选区,没有选区时复制上一条回复 |
ctrl+j |
换行而不发送 |
ctrl+c |
清空草稿(草稿为空时退出) |
tab |
接受输入框里那条灰色建议(草稿非空时仍是两个空格缩进) |
一轮结束后,空输入框会显示这条会话待办的下一件事(Next: …,取自会话的 todo
列表),按 tab 把它变成草稿再继续编辑;有草稿、! 命令行或正在跑的一轮里都不
会提出建议。
可在 ~/.config/miao/tui.json(或 miao.jsonc 的 keybinds)里重绑定。
5.2 会话与模型
Section titled “5.2 会话与模型”/model或ctrl+x m切换模型(会记住每个 agent 上次使用的模型)。miao session list/miao export <sessionID>管理与会话导出(输出 JSONL,每行一条已提交事件,便于 grep/备份)。miao run "..."非交互执行一次。
5.3 命令与技能
Section titled “5.3 命令与技能”- 斜杠命令:在 prompt 输入
/触发;命令来自commands配置。 - 技能(skills):按描述匹配,模型可用
skill工具加载技能内容。 - 自定义 agent 写在
agents配置里,用miao agent list查看。 - 完整命令清单见命令大全。
5.4 MCP
Section titled “5.4 MCP”在 mcp.servers 配置本地或远程服务器,其工具会以 mcp__<server>__<tool> 暴露给模型:
{ "mcp": { "servers": { "fs": { "type": "local", "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."] }, "remote": { "type": "remote", "url": "https://example.com/mcp" }, }, },}5.5 LSP 与格式化
Section titled “5.5 LSP 与格式化”lsp: true启用后,读/写文件会懒激活语言服务器,编辑后把诊断回灌给模型(LSP errors detected… please fix)。formatter: true启用后,edit/write/apply_patch成功后按扩展名跑格式化命令。- 侧边栏 LSP 一栏显示服务器连接状态;原生引擎会自己发现配置改动并就地增删语言服务器,不必重启;TypeScript 引擎仍在启动时读取配置。
5.6 内核级沙箱(需开启)
Section titled “5.6 内核级沙箱(需开启)”V2 bash 工具可以把每条命令放进 OS 沙箱运行:macOS 用 seatbelt,Linux 用 Landlock,Windows 暂无后端。可在配置中开启:
{ "sandbox": { "mode": "workspace-write", "network": true } }MIAO_SANDBOX=1、MIAO_SANDBOX_DENY_NETWORK=1 可覆盖配置。workspace-write 不限制读取,只允许写入当前 Location、命令工作目录、临时目录、writable_roots,以及被拦截后你批准的路径(命令会带该目录重跑)。网络默认允许,可显式禁止。沙箱已开启但主机没有后端时,on_unavailable 默认 "warn",命令不带沙箱运行;设为 "fail" 则直接拒绝。平台限制见 接入说明。
原生引擎自己的进程命令(bash、run_command、start_job、终端、hooks、格式化)始终在 OS 沙箱内运行,权限规则改变不了这一点——全量放行规则也抬不掉沙箱。同一个开关也是显式的运营者退出通道:配置里 sandbox.mode: "off" 或环境变量 MIAO_SANDBOX=0 会让引擎命令不带沙箱运行;MIAO_SANDBOX=1 或 mode: "workspace-write" 则保持约束。两者都没设置时,引擎保持沙箱。
5.7 成本与缓存遥测
Section titled “5.7 成本与缓存遥测”每轮 provider turn 记录 TTFT、缓存命中率、warm / expectedRebuild / cacheMiss 与成本;会话汇总。成本按模型费率估算,不等于供应商账单;侧边栏显示 % cached 与估算花费。
5.8 自治续跑循环(新)
Section titled “5.8 自治续跑循环(新)”让 agent「一轮又一轮」自己推进到 todo 全部完成:
{ "loop": { "enabled": true, "max_iterations": 25 } }行为:drain 收尾时若会话 todo 仍有未完成项,就自动追加一条续跑提示并继续;三道护栏——最大迭代数、成本预算(cost.budget_usd)、停滞检测(todo 连续 2 轮不变即停)。模型用 todowrite 维护清单,全部 completed/cancelled 自然结束。
5.9 中途补充要求,保留完整会话
Section titled “5.9 中途补充要求,保留完整会话”V2 在调度执行前先持久化输入。当前任务仍需继续时,执行中收到的 steer 输入在安全模型轮次边界生效;显式 queue 输入则等会话即将空闲时处理。两者语义不同,都不等于立即打断。普通 TUI 提交使用 steer。
例如先要求修复错误,再补充「保持公共 API 不变,并运行包内测试」。待处理输入会展示尚未进入模型历史的要求。公共 V2 API 还提供 queue 投递和 resume: false,后者只保存输入、不启动执行。
通过会话列表重新打开任务,或用 miao export <sessionID> 导出记录(JSONL)。历史可以跨终端生命周期保留,但崩溃不会自动重试未完成的模型执行。恢复时先检查已完成的改动;重复执行具有外部副作用的命令前,需要核实之前的执行结果。
5.10 专项子代理与项目内会话消息
Section titled “5.10 专项子代理与项目内会话消息”可以要求代理把范围明确的工作交给专项子代理,例如找出一个 API 的所有调用点,或审查数据库迁移。task 返回可通过会话 ID 继续的子会话,独立对话让主上下文不必装下全部调查细节。
V2 list_sessions 可发现同项目会话,send_message 接受会话 ID 或 @slug。消息带发送方标识,持久化进入目标收件箱,并受 message 权限和输入队列限额约束。默认 delivery: "steer" 在下一个安全轮次边界采纳;显式 delivery: "queue" 等会话即将空闲时再处理。跨项目目标会被拒绝。执行仍是进程内的;持久化输入可以送达由另一个本地活动窗口持有的会话,但不提供跨机器执行或自动恢复。
5.11 按任务调整上下文与成本
Section titled “5.11 按任务调整上下文与成本”{ "loop": { "enabled": true, "max_iterations": 25 }, "cost": { "budget_usd": 5 }, "compaction": { "prune": true }, "tool_output": { "max_lines": 2000, "max_bytes": 51200 },}这组可选配置组合了待办续跑、调度预算、旧输出裁剪和逐工具的模型可见输出限额。预算是真的会被执行的:会话级来自配置,Goal 级来自 goal.budget;花到五分之四时带剩余量告警一次,达到上限则在下一个模型轮次边界停止。已经准入的输入留在持久收件箱里等下一轮,模型不会为了迁就预算而被切换。金额只统计供应商上报的收费,涉及金额的提示会披露没有报价的轮次,并在账单结算前把剩余量说明为下界。预算不会中断正在执行的轮次,也不是账单硬上限。完整输出文件是临时的,受限的会话记录才是持久化历史。工具结果裁剪(微压缩)默认开启,可用 "prune": false 关闭。自动压缩默认在上下文达到窗口的 threshold(默认 0.9)时触发,并依据供应商回报的真实 prompt tokens 判断,因此会在窗口填满前提前压缩,而不是等到最后。主动压缩默认复用当前请求前缀做一次摘要,让供应商直接命中 prompt 缓存;只有前缀放不下指令时才回退到分阶段恢复,可用 "hot_prefix": false 强制走分阶段策略。廉价模型摘要仍需单独开启,开启前先确认解析出的廉价模型适合当前供应商和任务。
compaction.max_context 让模型在比其声明窗口更小的范围内工作,用于控制成本、延迟或缓存抖动。它接受一个作用于所有模型的值,或以 "<providerID>/<modelID>" 为键的映射(支持 */? 通配,最长匹配键胜出):可以是 token 数、"300K" / "1.5M" 简写,或模型窗口的 "50%"。该值只会被钳制到模型真实窗口之内,绝不会抬高它;压缩、上下文提示与溢出恢复都按钳制后的窗口规划。由于配置合并不支持删除键,0 表示恢复模型默认。
被压缩出模型窗口的原文仍然持久化在磁盘上。recall 工具按关键词检索这段历史,让 agent 找回被摘要丢掉的细节,而不必重新读文件或重复已完成的工作;history 工具则按位置分页读取完整的历史消息(history(from: …) 继续下一页),每页都有预算上限。
6. 运行时状态与后续工作
Section titled “6. 运行时状态与后续工作”所有已发布客户端都使用单一 V2 会话运行时;V1 会话运行时及其 /session/* 路由已删除。
- V1 退役计划 记录了删除过程和剩余兼容面(数据库迁移与非会话旧路由)。
- 会话存储设计 记录存储方案。可用
miao db stats、miao db vacuum和 JSONL 导出检查、维护本地记录。 - 代理并发 设计非阻塞子代理与完成即唤醒,避免长任务卡住会话。
- 崩溃后自动执行恢复与集群所有权尚未实现。OS 沙箱已内置于 V2
bash工具但仍需开启,见 原生组件与沙箱范围。
7. 常见问题(FAQ)
Section titled “7. 常见问题(FAQ)”高频问题已经整理成独立页面:常见问题(FAQ),覆盖安装升级、供应商与模型、权限、配置、MCP、数据位置和排障。这里只保留两个最容易影响使用的点:
- 侧边栏显示 “LSPs are disabled”:配置里没写
lsp(省略即禁用)。在miao.jsonc加"lsp": true,原生引擎会重载配置并连接语言服务器。 ctrl+x b打不开侧边栏:子会话(由 task/subagent 派生、parent_id非空)会强制隐藏侧边栏;窄终端(宽度 ≤120)的 auto 模式也不默认显示,但手动 toggle 有效。
miao db path # 数据库路径miao db stats # 表/事件占用(定位膨胀)miao db vacuum --apply # 回收空闲页miao db backup --to <path> # 校验过的数据库备份miao export <sessionID> # 导出会话为 JSONLMIAO_CONFIG=/path/miao.jsonc miao # 指定配置日志位于 ~/.local/share/miao/log/。用 miao db stats 监控膨胀,需要时用 miao db vacuum --apply 回收空闲页;miao db retention 只报告可能被保留策略删除的事件,不会直接删除。
bun installbun run dev # 源码运行(等价 miao-dev)bun --cwd packages/miao typecheckbun --cwd packages/miao test./script/install-local.sh --binary /path/to/prebuilt/miao # 安装构建机产物Synced from mttydev/miao@2f6034b.