Skip to content

whiter001/minimax-v

BranchesTags

Repository files navigation

MiniMax V CLI

MiniMax V CLI 是一个用 V 语言实现的本地 AI Agent 运行时，提供统一的命令行入口，把模型调用、工具执行、MCP 集成、技能体系和终端交互组合在一起。

当前文档以源码为准，重点覆盖已经进入主分支的能力，不再保留阶段性报告和历史草稿。

项目定位

这个项目不是单纯的 API 封装器，而是一个可在本机执行动作的 CLI Agent：

  • 支持单次提问和持续交互。
  • 支持工具调用循环，而不是只返回一次文本。
  • 支持 MCP 工具发现和接入。
  • 支持 Skills、Custom Commands、Extensions、Experience 等扩展机制。
  • 支持普通 REPL、term.ui 和 ACP server 三种主要交互形态。

快速开始

1. 配置 API Key

mkdir -p ~/.config/minimax
cat > ~/.config/minimax/config <<'EOF'
api_key=sk-cp-xxx
EOF

也可以使用环境变量：

export MINIMAX_API_KEY=sk-cp-xxx

2. 构建

./build.sh

等价命令：

v -o minimax_cli src/

构建选项

开发构建

v -o minimax_cli src/

生产构建

v -prod -o minimax_cli src/

调试构建

v -g -o minimax_cli src/

3. 运行

./minimax_cli -p "用 V 语言写一个 Hello World"
./minimax_cli
./minimax_cli --term-ui
./minimax_cli --enable-tools -p "读取当前目录的文件列表"
./minimax_cli --mcp -p "搜索一下 V 语言最新版本"
./minimax_cli --acp
./minimax_cli --quota

核心能力

基础调用

  • Headless 模式：使用 -p 或 --prompt 发起单次请求。
  • Prompt 后继续交互：使用 -i 或 --prompt-interactive，先执行首个问题再进入 REPL。
  • REPL 模式：默认进入交互会话。
  • 流式输出：通过 --stream 输出 SSE 流。
  • 输出格式：headless 模式支持 text、json、plain。

工具调用

启用 --enable-tools 后，模型可以调用本地工具执行动作。当前内置工具体系包括：

  • 持久化 Bash 会话。
  • 读写文件与列目录。
  • 结构化文本替换与插入。
  • grep、find、json 编辑。
  • ask_user、session notes、todo、checkpoint。
  • 桌面控制和截图工具。
  • 文生图 / 文生音频 / 文件列出（调用 MiniMax 图像生成、语音合成与文件管理 API，也支持 speech / tts / files list 直连命令；speech 还支持 --text-file 和 --split）。

补充说明：

  • 生成图像默认读取单独的 image_model 和 image_api_url 配置；当用户明显要求生成图片、海报、封面、插画等视觉内容时，模型会被提示优先调用 generate_image 工具。
  • Windows 下 bash 工具默认仍保持持久 shell 语义；针对 nu ...、pwsh ...、pueue ... 这类命令会优先走直执行路径，以避免部分 Git Bash 子进程环境与后台任务环境不一致。

工具执行具有危险命令过滤，不会无条件放开系统破坏性命令。

MCP

使用 --mcp 时：

  • 从 ~/.config/minimax/mcp.json 加载额外 MCP 服务（如 Playwright）。
  • 默认不预置 MiniMax MCP；如需 MCP 工具，请通过 --mcp 加载外部配置。

交互增强

  • term.ui：状态栏、活动流、工具状态和 ask_user 交互。
  • @文件引用：把文件内容附加到问题中。
  • 手动工具前缀：#read、#write、#ls、#run。
  • 文件管理直连命令：files list --purpose voice_clone|prompt_audio|t2a_async_input。
  • Shell 直达：!command。

扩展能力

  • Skills：按目录自动发现和切换，默认扫描 ~/.config/minimax/skills / ~/.agents/skills，项目级 .agents/skills 需要先设置 --workspace 或 MINIMAX_WORKSPACE；SKILL.md 支持 tags / tools / triggers / platform frontmatter；启用 --auto-skills 后会先在本地筛出最相关的 skills 和片段，再让 AI 决定是否激活最合适的 skill。
  • SOPs：默认扫描 ~/.config/minimax/sops/<skill>/SOP.md；开启工具调用后会自动暴露可用 SOP，并在任务匹配时先读取对应 SOP 作为执行前检查。
  • Custom Commands：基于 TOML 的命令模板。
  • Extensions：安装、启用、更新命令与 MCP 组合包。
  • Experience：把经验记录到本地知识库，并自动写回全局 skill 与全局 SOP。
  • Cron：本地定时任务子命令，支持 cron dashboard 本地页面查看任务与执行记录。
  • Subagent（子 Agent）：主 agent 可以通过 spawn_subagent 单次起子 agent，或通过 agent_swarm 批量并行起多个子 agent。三种内置 profile（coder 全工具、explore 只读、plan 只规划）。每个子 agent 上下文完全隔离，跑完后把摘要回填给主 agent，trajectory 单独存到 ~/.config/minimax/trajectories/subagent_<id>.json。并发数、超时、嵌套深度、ramp 间隔都可配。

Subagent 用法

主 agent 在对话中会自己决定何时调用 subagent。你也可以直接通过 headless 触发：

# 单个 subagent（让 coder 帮我修 src/foo.v）
minimax_cli -p '用 spawn_subagent 帮我修 src/foo.v 的 bug，profile=coder，prompt=阅读 src/foo.v 后定位并修复编译错误'

# 批量 swarm（并行看 src/ 下所有 .v 文件）
minimax_cli -p '用 agent_swarm 并行总结 src/ 下每个 .v 文件的职责，profile=explore，items=["src/main.v","src/agent.v","src/client.v"]'

子 agent 的工具调用结果会作为 tool_result 回填给主 agent；trajectory 文件保留完整执行轨迹便于回放调试。

默认配置

默认值来自 src/config.v：

api_url=https://api.minimaxi.com/anthropic/v1/messages
model=MiniMax-M3
temperature=1.0
max_tokens=32768
max_rounds=5000
token_limit=80000
enable_tools=true
auto_skills=true
auto_check_sops=true
auto_write_skills=true
auto_upgrade_sops=true
knowledge_sync_mode=balanced
enable_desktop_control=false
enable_screen_capture=true
enable_logging=true
debug=false
smtp_server=
smtp_port=587
smtp_username=
smtp_password=
smtp_from=
image_api_url=https://api.minimaxi.com/v1/image_generation
image_model=image-01
subagent_max_concurrency=5
subagent_default_timeout_ms=1800000
subagent_max_depth=3
subagent_summary_min_length=200
subagent_ramp_interval_ms=700

SMTP 全局配置用于 send_mail 工具。配置后，调用邮件工具时可以直接复用这些默认值，只在需要时通过工具参数覆盖。对应环境变量为：

  • MINIMAX_SMTP_SERVER
  • MINIMAX_SMTP_PORT
  • MINIMAX_SMTP_USERNAME
  • MINIMAX_SMTP_PASSWORD
  • MINIMAX_SMTP_FROM

图像生成同样可以单独设置：

  • MINIMAX_IMAGE_API_URL
  • MINIMAX_IMAGE_MODEL

对应的配置项为：

  • image_api_url
  • image_model

配置文件位置：

  • 主路径：~/.config/minimax/config
  • 兼容旧路径：~/.minimax_config

常用命令

CLI 参数

  • -p, --prompt PROMPT（单次提问后退出）
  • -i, --prompt-interactive [PROMPT]（执行首个问题后继续交互）
  • --model NAME
  • --temperature (0.0, 1.0]
  • --max-tokens N
  • --max-rounds N
  • --token-limit N
  • --system PROMPT
  • --workspace PATH
  • --skill NAME
  • --auto-skills
  • --skills
  • --stream
  • --enable-tools
  • --enable-desktop-control
  • --enable-screen-capture
  • --mcp
  • --acp
  • --term-ui
  • --log
  • --trajectory
  • --plan
  • --output-format text|json|plain
  • --quota

交互模式命令

  • exit, quit
  • clear
  • config
  • doctor
  • tools, tools on, tools off
  • skills, skills reload, skills create NAME, skills sync NAME|all [mode]
  • sops, sops list, sops show NAME, sops sync NAME|all [mode]
  • skill NAME
  • experience add, list, show, search, prune
  • commands list, commands show NAME, commands reload
  • extensions list, show, install, enable, disable, uninstall, update
  • notes, notes clear
  • log, trajectory, plan
  • checkpoint, checkpoints, restore
  • quota
  • cron ... / cron dashboard
  • mcp, mcp start, mcp stop
  • files, files list
  • speech, tts

准确行为以 src/main.v 的帮助文本和命令分发逻辑为准。

补充说明：

  • --enable-tools 开启时，模型会收到已发现 skills 的元信息，并可通过 activate_skill 工具自行加载对应 skill。
  • --auto-skills 会显式鼓励模型优先自行选择匹配的 skill；若未设置 workspace，会默认使用当前目录以纳入项目级 .agents/skills。
  • 开启工具调用且存在全局 SOP 时，模型会先调用 match_sop 工具匹配最相关的 SOP。该工具会返回分项评分、命中层级以及 suggested_read_order，模型再按建议顺序用 read_file 读取对应 SOP；可通过 auto_check_sops=false 或环境变量 MINIMAX_AUTO_CHECK_SOPS=0 关闭。
  • experience add 默认会按 knowledge_sync_mode 自动同步到全局 ~/.config/minimax/skills 和 ~/.config/minimax/sops；可通过 auto_write_skills、auto_upgrade_sops 或对应环境变量关闭。
  • AI 开启工具调用后，还可以直接使用 record_experience 工具沉淀经验，不必依赖交互命令。

文档索引

测试与验证

v test src/
./tests/check_vfmt.sh
./integration_test.sh
./comprehensive_test.sh
./tests/verify_speech_synthesis.sh [--with-api]
./tests/verify_image_generation.sh [--with-api]

如果需要启用 Git hooks：

bash scripts/install-git-hooks.sh

当前 hooks 约定：

  • pre-commit 运行 tests/check_vfmt.sh
  • pre-push 运行 build.sh 和 v test src/

语音合成验证脚本会从同一个 ~/.config/minimax/config 读取 api_key，并用这把 key 依次验证多个模型的短文本合成与分段输出。

图像生成验证脚本也会从同一个 ~/.config/minimax/config 读取 api_key，并用这把 key 依次验证多个模型名；如果当前 token plan 不支持 image-01-live，脚本会明确跳过。

前置依赖

  • V 编译器。
  • MCP 场景下需要对应工具运行时，例如 npx 或 uv。
  • Windows 上安装 uv 的常用方式：
irm https://astral.sh/uv/install.ps1 | iex
winget install --id=astral-sh.uv -e
  • 如果你在代理环境下安装，先为当前 PowerShell 会话设置 HTTP_PROXY 和 HTTPS_PROXY，例如 http://127.0.0.1:7788。
  • 如果使用 SQLite 经验库存储，系统中需要可用的 sqlite3。

许可证

MIT

About

agent cli with minimax-m3 in v

Resources

Readme
Activity

Stars

8 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages