https://github.com/whiter001/minimax-v

agent cli with minimax-m3 in v
https://github.com/whiter001/minimax-v

Last synced: 3 days ago
JSON representation

agent cli with minimax-m3 in v

• Host: GitHub
• URL: https://github.com/whiter001/minimax-v
• Owner: whiter001
• Created: 2026-03-11T00:54:03.000Z (5 months ago)
• Default Branch: main
• Last Pushed: 2026-07-13T08:59:58.000Z (12 days ago)
• Last Synced: 2026-07-22T14:34:36.758Z (3 days ago)
• Language: V
• Homepage:
• Size: 602 KB
• Stars: 8
• Watchers: 0
• Forks: 2
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Agents: AGENTS.md

Awesome Lists containing this project

• awesome-v - minimax-v - Local AI Agent runtime implemented in the V language. (Applications / Command-line)

README

          
# 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

```bash

mkdir -p ~/.config/minimax

cat > ~/.config/minimax/config <<'EOF'

api_key=sk-cp-xxx

EOF

```

也可以使用环境变量：

```bash

export MINIMAX_API_KEY=sk-cp-xxx

```

### 2. 构建

```bash

./build.sh

```

等价命令：

```bash

v -o minimax_cli src/

```

### 构建选项

#### 开发构建

```bash

v -o minimax_cli src/

```

#### 生产构建

```bash

v -prod -o minimax_cli src/

```

#### 调试构建

```bash

v -g -o minimax_cli src/

```

### 3. 运行

```bash

./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//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_.json`。并发数、超时、嵌套深度、ramp 间隔都可配。

- Hooks（用户自定义钩子）：在 `~/.config/minimax/hooks.json` 里声明 shell 命令，在工具执行、会话起止、上下文压缩等事件点触发；`PreToolUse` / `UserPromptSubmit` / `Stop` 可阻断（退出码 2 = deny），适合做安全护栏和自动化。

### Hooks 用法

配置文件 `~/.config/minimax/hooks.json`（不存在则钩子全部禁用）：

```json

{

  "hooks": [

    {"event": "PreToolUse", "matcher": "bash", "command": "echo 'bash 被护栏禁止' >&2; exit 2", "timeout": 10},

    {"event": "PostToolUse", "command": "cat \"$MINIMAX_HOOK_INPUT\" >> ~/.config/minimax/hook_audit.log", "timeout": 10}

  ]

}

```

- `event`：支持 `UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`Stop`、`SessionStart`、`SessionEnd`、`PreCompact`、`PostCompact`。

- `matcher`：可选，对事件的匹配值做区分大小写的子串匹配（`PreToolUse`/`PostToolUse` 匹配工具名，`UserPromptSubmit` 匹配输入文本）；省略则全匹配。

- `command`：通过 bash 执行的命令。事件 payload（JSON，含 `hook_event_name`/`session_id`/`cwd` 及事件特有字段如 `tool_name`/`tool_input`）写入临时文件，路径通过环境变量 `MINIMAX_HOOK_INPUT` 传入。

- `timeout`：可选，秒，默认 30，上限 600。

- 阻断语义：仅 `UserPromptSubmit` / `PreToolUse` / `Stop` 可阻断——退出码 2 表示 deny，stderr 内容作为原因回传给模型；其他退出码、超时、命令不存在一律 fail-open（放行），避免钩子故障卡死主流程。

### Subagent 用法

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

```bash

# 单个 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](src/config.v)：

```ini

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](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` 工具沉淀经验，不必依赖交互命令。

## 文档索引

- [docs/README.md](docs/README.md)：文档入口。

- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)：系统结构和数据流。

- [docs/IMPLEMENTATION.md](docs/IMPLEMENTATION.md)：源码模块职责映射。

- [docs/EXTENSIBILITY.md](docs/EXTENSIBILITY.md)：MCP、技能、命令模板、扩展、经验库。

- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)：开发、格式化、测试与排障约定。

## 测试与验证

```bash

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

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 的常用方式：

```powershell

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