mbridge 命令行
一个 CLI，覆盖从持续会话、单轮问答、diff 编辑、路由、成本预算、模型管理、缓存、MCP、Skills 的全部场景。
所有子命令
运行 mbridge --help 查看完整列表。 每个子命令也支持 --help。
REPL / 单轮
mbridge— 进入持续会话mbridge -m NAME --cwd PATH— 切模型 / 切目录mbridge --allow-bash— 开启run_bash工具mbridge --yes— 跳过写/编辑/bash 确认弹窗mbridge ask "..."— 单轮请求mbridge edit "..."— 让 AI 出 diff 改代码mbridge run "pytest -x"— 白名单 shell 命令mbridge route "..."— 路由分析（不实调）
模型 & 配置
mbridge init— 初始化~/.modelbridge/mbridge model init / add / list / removembridge config show / upgradembridge config profile add/list/use/show/removembridge doctor— 全局自检mbridge doctor model NAME— 单模型自检mbridge doctor route— 路由自检
成本 · 缓存
mbridge usage cost "..."— 成本估算mbridge usage budget [set ...]— 月度预算mbridge usage cache— 缓存命中统计
提示词 · 规则 · Skills
mbridge prompt list/show/edit/set-system/resetmbridge project scan / rules / rules initmbridge skill list/show/add/removembridge project init [--force]— 生成AGENT.md
MCP · 浏览器
mbridge mcp list / tools / resources / promptsmbridge mcp serve— 把 ModelBridge 暴露成 MCP servermbridge bridge install / status / on / offmbridge bridge control on/off/status— 侧边栏联动
其它
mbridge version [--check]— 显示版本号mbridge --version / -Vmbridge update [--yes]— 检查并下载新版本mbridge --install-completion— shell 补全
持续会话 · 像 Claude Code 一样
直接运行 mbridge 进入交互式会话。 AI 一直保留上下文，能主动调用工具读写文件。
$ mbridge -m deepseek-chat
┌─ mbridge ──────────────────────────────────────────┐
│ ModelBridge agent REPL │
│ model : deepseek-chat │
│ cwd : /home/me/my-project │
│ tools : list_dir, read_file, str_replace, write_file
│ approval : 每次询问 │
│ allow_bash: False │
└────────────────────────────────────────────────────────┘
you: 看一下 src/auth.py，告诉我 login 函数有什么问题
[tool · read_file (path=src/auth.py)] ...
[assistant] 这个函数有几个问题：1) ... 2) ...
you: 帮我用 str_replace 修掉第二个
[tool · str_replace (path=src/auth.py, old_str=…)]
批准 · str_replace
- if token == None:
+ if token is None:
执行? [y]es / [N]o / [a]lways y
[assistant] 已修复。运行测试确认一下？
you: /exit
[bye]
session saved → ~/.modelbridge/sessions/2026-05-23_153012_repl_deepseek-chat.json
/exit//quit— 退出/clear— 清空历史（system prompt 保留）/init [--force]— 扫描项目并生成AGENT.md（写前给预览）/rules·/prompt·/debug on|off·/version·/updateCtrl-D— 退出
工具集
| 工具 | 用途 | 需要确认 |
|---|---|---|
read_file(path) | 读文件；图片在 vision 模型下直接识别 | 否 |
list_dir(path) | 列目录（默认隐藏点文件） | 否 |
write_file(path, content) | 覆盖 / 创建文件（500 KB 上限） | 是 |
str_replace(path, old, new) | 精确替换；要求 old 唯一出现 | 是 |
run_bash(command) | shell；30s 超时；输出截 8 KB | 是（且需 --allow-bash） |
确认弹窗三个选项： y 同意这一次 · N 拒绝（默认） · a 本会话内对该工具始终同意。
让 AI Coding Agent 长期降本
ModelBridge 的核心能力之一是：简单任务自动用便宜 / 本地模型，复杂任务自动升级到强模型。
5 档任务等级
| 等级 | 用途 |
|---|---|
tiny | 意图分类 / 是非判断 / 便宜预处理 |
cheap | 普通问答 / 解释报错 / 简单代码解释 |
coder | 单文件代码生成 / 简单 bug 修复 / 生成 diff |
agent | 多文件任务 / 工具调用 / MCP |
expert | 架构重构 / 安全审查 / 多次失败的兜底 |
3 种路由模式
| 模式 | 取舍 |
|---|---|
economy | 尽量 tiny / cheap，失败再升级，偏好本地 / cache 友好 |
balanced | 默认 · 普通问 cheap、代码 coder、复杂 agent，失败 fallback expert |
powerful | 代码直接 coder/agent，架构直接 expert，少考虑成本 |
mbridge route "帮我修复登录 bug" --mode economy # → cheap
mbridge route "帮我修复登录 bug" --mode balanced # → coder
mbridge route "帮我修复登录 bug" --mode powerful # → agent
mbridge route test # 8 题套件
mbridge ask "解释这个报错" --route # 自动 cheap
mbridge ask "写一个 FastAPI hello" --route --fallback
mbridge ask "..." --route --mode powerful --fallback
升级触发条件：超时、429、provider 400、空内容、模型明确说做不了。
--fallback 失败时按 tiny→cheap→coder→agent→expert 向上重试，受 routing.fallback.max_upgrade_steps 限制（默认 2）。
预算守卫
mbridge usage budget set --monthly 30 --daily 2 --warn-at 80 --hard-stop
mbridge usage budget
--warn-at N：到达 N% 时打 warning。 --hard-stop：超额时阻止非本地模型调用（本地模型永远允许）。 跨货币的开销只入 history、不并入 spent。
AGENT.md · CLAUDE.md · .cursorrules 自动加载
ModelBridge 优先遵守项目规则文件。 项目规则文件越清楚，AI 后续改代码越稳定。
支持的规则文件（按优先级，顶部覆盖底部）
| 位置 | 文件 |
|---|---|
| 项目根目录 | AGENT.md · AGENTS.md · CLAUDE.md · .cursorrules · .windsurfrules |
| 项目 .modelbridge/ | rules.md · prompt.md |
| 用户全局 | ~/.modelbridge/system.md · ~/.modelbridge/rules.md |
多个文件都存在时全部合并，每个文件前会插一个 # Rules from <name> (scope) 标题，方便 debug。
自动生成 AGENT.md
mbridge project init --path . --model deepseek-chat
# 或在 REPL 里：
> /init # 扫描项目并生成 AGENT.md，写前给预览
> /init --force # 已有 AGENT.md 时覆盖
生成的 AGENT.md 包含 8 个段：Project Overview / Tech Stack / Common Commands / Directory Structure / Coding Rules / Agent Instructions / Safety Rules / Known Notes。
AI 永远不能直接动你的文件
AI 只能输出一段 unified diff，ModelBridge 负责解析 · 校验 · 备份 · 应用 · 回滚。
# 让模型生成 diff（不应用，仅展示）
mbridge edit "给 README 加一段介绍" --project . --dry-run
# 完整流程：生成 → 安全检查 → 展示 → 确认 → 备份 → 应用
mbridge edit "修复登录 bug" --project .
# 跳过最终确认（但安全检查 + 备份照常）
mbridge edit "修复 typo" --project . --yes
# 应用磁盘上的现成 patch
mbridge patch preview path/to/x.patch
mbridge patch apply path/to/x.patch --yes
mbridge patch apply path/to/x.patch --dry-run
# 回滚最近一次 apply
mbridge patch rollback- 安全检查：拒绝绝对路径 /
..跳目录 / 命中.git .ssh .env id_rsa等敏感路径。 - 备份：每次 apply 前落
.modelbridge/backups/<ts>/，含 patch + 原始文件。 - 回滚：
rollback选最新非.rolledback目录逐文件恢复。 - 不盲信行号：hunk 用 context + removed 块作锚点 ±5 行模糊匹配。
- --yes 不是 YOLO：只是跳过"确认应用"那一步弹窗，安全检查、备份照常。