{"id":49884001,"url":"https://github.com/whiter001/minimax-v","last_synced_at":"2026-07-22T14:34:47.983Z","repository":{"id":343612629,"uuid":"1178374780","full_name":"whiter001/minimax-v","owner":"whiter001","description":"agent cli with minimax-m3 in v","archived":false,"fork":false,"pushed_at":"2026-07-13T08:59:58.000Z","size":616,"stargazers_count":8,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-22T14:34:36.758Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"V","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/whiter001.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-11T00:54:03.000Z","updated_at":"2026-07-17T14:19:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/whiter001/minimax-v","commit_stats":null,"previous_names":["whiter001/minimax-v"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/whiter001/minimax-v","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiter001%2Fminimax-v","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiter001%2Fminimax-v/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiter001%2Fminimax-v/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiter001%2Fminimax-v/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/whiter001","download_url":"https://codeload.github.com/whiter001/minimax-v/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiter001%2Fminimax-v/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35766428,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-22T02:00:06.236Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-15T17:00:45.923Z","updated_at":"2026-07-22T14:34:47.969Z","avatar_url":"https://github.com/whiter001.png","language":"V","funding_links":[],"categories":["Applications"],"sub_categories":["Command-line"],"readme":"# MiniMax V CLI\n\nMiniMax V CLI 是一个用 V 语言实现的本地 AI Agent 运行时，提供统一的命令行入口，把模型调用、工具执行、MCP 集成、技能体系和终端交互组合在一起。\n\n当前文档以源码为准，重点覆盖已经进入主分支的能力，不再保留阶段性报告和历史草稿。\n\n## 项目定位\n\n这个项目不是单纯的 API 封装器，而是一个可在本机执行动作的 CLI Agent：\n\n- 支持单次提问和持续交互。\n- 支持工具调用循环，而不是只返回一次文本。\n- 支持 MCP 工具发现和接入。\n- 支持 Skills、Custom Commands、Extensions、Experience 等扩展机制。\n- 支持普通 REPL、term.ui 和 ACP server 三种主要交互形态。\n\n## 快速开始\n\n### 1. 配置 API Key\n\n```bash\nmkdir -p ~/.config/minimax\ncat \u003e ~/.config/minimax/config \u003c\u003c'EOF'\napi_key=sk-cp-xxx\nEOF\n```\n\n也可以使用环境变量：\n\n```bash\nexport MINIMAX_API_KEY=sk-cp-xxx\n```\n\n### 2. 构建\n\n```bash\n./build.sh\n```\n\n等价命令：\n\n```bash\nv -o minimax_cli src/\n```\n\n### 构建选项\n\n#### 开发构建\n```bash\nv -o minimax_cli src/\n```\n\n#### 生产构建\n```bash\nv -prod -o minimax_cli src/\n```\n\n#### 调试构建\n```bash\nv -g -o minimax_cli src/\n```\n\n### 3. 运行\n\n```bash\n./minimax_cli -p \"用 V 语言写一个 Hello World\"\n./minimax_cli\n./minimax_cli --term-ui\n./minimax_cli --enable-tools -p \"读取当前目录的文件列表\"\n./minimax_cli --mcp -p \"搜索一下 V 语言最新版本\"\n./minimax_cli --acp\n./minimax_cli --quota\n```\n\n## 核心能力\n\n### 基础调用\n\n- Headless 模式：使用 -p 或 --prompt 发起单次请求。\n- Prompt 后继续交互：使用 `-i` 或 `--prompt-interactive`，先执行首个问题再进入 REPL。\n- REPL 模式：默认进入交互会话。\n- 流式输出：通过 --stream 输出 SSE 流。\n- 输出格式：headless 模式支持 text、json、plain。\n\n### 工具调用\n\n启用 --enable-tools 后，模**型可以调用本地工具执行动作。当前内置工具体系包**括：\n\n- 持久化 Bash 会话。\n- 读写文件与列目录。\n- 结构化文本替换与插入。\n- grep、find、json 编辑。\n- ask\\_user、session notes、todo、checkpoint。\n- 桌面控制和截图工具。\n- 文生图 / 文生音频 / 文件列出（调用 MiniMax 图像生成、语音合成与文件管理 API，也支持 `speech` / `tts` / `files list` 直连命令；speech 还支持 `--text-file` 和 `--split`）。\n\n补充说明：\n\n- 生成图像默认读取单独的 `image_model` 和 `image_api_url` 配置；当用户明显要求生成图片、海报、封面、插画等视觉内容时，模型会被提示优先调用 `generate_image` 工具。\n- Windows 下 `bash` 工具默认仍保持持久 shell 语义；针对 `nu ...`、`pwsh ...`、`pueue ...` 这类命令会优先走直执行路径，以避免部分 Git Bash 子进程环境与后台任务环境不一致。\n\n工具执行具有危险命令过滤，不会无条件放开系统破坏性命令。\n\n### MCP\n\n使用 --mcp 时：\n\n- 从 \\~/.config/minimax/mcp.json 加载额外 MCP 服务（如 Playwright）。\n- 默认不预置 MiniMax MCP；如需 MCP 工具，请通过 --mcp 加载外部配置。\n\n### 交互增强\n\n- term.ui：状态栏、活动流、工具状态和 ask\\_user 交互。\n- @文件引用：把文件内容附加到问题中。\n- 手动工具前缀：#read、#write、#ls、#run。\n- 文件管理直连命令：`files list --purpose voice_clone|prompt_audio|t2a_async_input`。\n- Shell 直达：!command。\n\n### 扩展能力\n\n- Skills：按目录自动发现和切换，默认扫描 `~/.config/minimax/skills` / `~/.agents/skills`，项目级 `.agents/skills` 需要先设置 `--workspace` 或 `MINIMAX_WORKSPACE`；`SKILL.md` 支持 `tags` / `tools` / `triggers` / `platform` frontmatter；启用 `--auto-skills` 后会先在本地筛出最相关的 skills 和片段，再让 AI 决定是否激活最合适的 skill。\n- SOPs：默认扫描 `~/.config/minimax/sops/\u003cskill\u003e/SOP.md`；开启工具调用后会自动暴露可用 SOP，并在任务匹配时先读取对应 SOP 作为执行前检查。\n- Custom Commands：基于 TOML 的命令模板。\n- Extensions：安装、启用、更新命令与 MCP 组合包。\n- Experience：把经验记录到本地知识库，并自动写回全局 skill 与全局 SOP。\n- Cron：本地定时任务子命令，支持 `cron dashboard` 本地页面查看任务与执行记录。\n- Subagent（子 Agent）：主 agent 可以通过 `spawn_subagent` 单次起子 agent，或通过 `agent_swarm` 批量并行起多个子 agent。三种内置 profile（`coder` 全工具、`explore` 只读、`plan` 只规划）。每个子 agent 上下文完全隔离，跑完后把摘要回填给主 agent，trajectory 单独存到 `~/.config/minimax/trajectories/subagent_\u003cid\u003e.json`。并发数、超时、嵌套深度、ramp 间隔都可配。\n- Hooks（用户自定义钩子）：在 `~/.config/minimax/hooks.json` 里声明 shell 命令，在工具执行、会话起止、上下文压缩等事件点触发；`PreToolUse` / `UserPromptSubmit` / `Stop` 可阻断（退出码 2 = deny），适合做安全护栏和自动化。\n\n### Hooks 用法\n\n配置文件 `~/.config/minimax/hooks.json`（不存在则钩子全部禁用）：\n\n```json\n{\n  \"hooks\": [\n    {\"event\": \"PreToolUse\", \"matcher\": \"bash\", \"command\": \"echo 'bash 被护栏禁止' \u003e\u00262; exit 2\", \"timeout\": 10},\n    {\"event\": \"PostToolUse\", \"command\": \"cat \\\"$MINIMAX_HOOK_INPUT\\\" \u003e\u003e ~/.config/minimax/hook_audit.log\", \"timeout\": 10}\n  ]\n}\n```\n\n- `event`：支持 `UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`Stop`、`SessionStart`、`SessionEnd`、`PreCompact`、`PostCompact`。\n- `matcher`：可选，对事件的匹配值做区分大小写的子串匹配（`PreToolUse`/`PostToolUse` 匹配工具名，`UserPromptSubmit` 匹配输入文本）；省略则全匹配。\n- `command`：通过 bash 执行的命令。事件 payload（JSON，含 `hook_event_name`/`session_id`/`cwd` 及事件特有字段如 `tool_name`/`tool_input`）写入临时文件，路径通过环境变量 `MINIMAX_HOOK_INPUT` 传入。\n- `timeout`：可选，秒，默认 30，上限 600。\n- 阻断语义：仅 `UserPromptSubmit` / `PreToolUse` / `Stop` 可阻断——退出码 2 表示 deny，stderr 内容作为原因回传给模型；其他退出码、超时、命令不存在一律 fail-open（放行），避免钩子故障卡死主流程。\n\n### Subagent 用法\n\n主 agent 在对话中会自己决定何时调用 subagent。你也可以直接通过 headless 触发：\n\n```bash\n# 单个 subagent（让 coder 帮我修 src/foo.v）\nminimax_cli -p '用 spawn_subagent 帮我修 src/foo.v 的 bug，profile=coder，prompt=阅读 src/foo.v 后定位并修复编译错误'\n\n# 批量 swarm（并行看 src/ 下所有 .v 文件）\nminimax_cli -p '用 agent_swarm 并行总结 src/ 下每个 .v 文件的职责，profile=explore，items=[\"src/main.v\",\"src/agent.v\",\"src/client.v\"]'\n```\n\n子 agent 的工具调用结果会作为 `tool_result` 回填给主 agent；trajectory 文件保留完整执行轨迹便于回放调试。\n\n## 默认配置\n\n默认值来自 [src/config.v](src/config.v)：\n\n```ini\napi_url=https://api.minimaxi.com/anthropic/v1/messages\nmodel=MiniMax-M3\ntemperature=1.0\nmax_tokens=32768\nmax_rounds=5000\ntoken_limit=80000\nenable_tools=true\nauto_skills=true\nauto_check_sops=true\nauto_write_skills=true\nauto_upgrade_sops=true\nknowledge_sync_mode=balanced\nenable_desktop_control=false\nenable_screen_capture=true\nenable_logging=true\ndebug=false\nsmtp_server=\nsmtp_port=587\nsmtp_username=\nsmtp_password=\nsmtp_from=\nimage_api_url=https://api.minimaxi.com/v1/image_generation\nimage_model=image-01\nsubagent_max_concurrency=5\nsubagent_default_timeout_ms=1800000\nsubagent_max_depth=3\nsubagent_summary_min_length=200\nsubagent_ramp_interval_ms=700\n```\n\nSMTP 全局配置用于 `send_mail` 工具。配置后，调用邮件工具时可以直接复用这些默认值，只在需要时通过工具参数覆盖。对应环境变量为：\n\n- `MINIMAX_SMTP_SERVER`\n- `MINIMAX_SMTP_PORT`\n- `MINIMAX_SMTP_USERNAME`\n- `MINIMAX_SMTP_PASSWORD`\n- `MINIMAX_SMTP_FROM`\n\n图像生成同样可以单独设置：\n\n- `MINIMAX_IMAGE_API_URL`\n- `MINIMAX_IMAGE_MODEL`\n\n对应的配置项为：\n\n- `image_api_url`\n- `image_model`\n\n配置文件位置：\n\n- 主路径：\\~/.config/minimax/config\n- 兼容旧路径：\\~/.minimax\\_config\n\n## 常用命令\n\n### CLI 参数\n\n- -p, --prompt PROMPT（单次提问后退出）\n- -i, --prompt-interactive \\[PROMPT]（执行首个问题后继续交互）\n- \\--model NAME\n- \\--temperature (0.0, 1.0]\n- \\--max-tokens N\n- \\--max-rounds N\n- \\--token-limit N\n- \\--system PROMPT\n- \\--workspace PATH\n- \\--skill NAME\n- \\--auto-skills\n- \\--skills\n- \\--stream\n- \\--enable-tools\n- \\--enable-desktop-control\n- \\--enable-screen-capture\n- \\--mcp\n- \\--acp\n- \\--term-ui\n- \\--log\n- \\--trajectory\n- \\--plan\n- \\--output-format text|json|plain\n- \\--quota\n\n### 交互模式命令\n\n- exit, quit\n- clear\n- config\n- doctor\n- tools, tools on, tools off\n- skills, skills reload, skills create NAME, skills sync NAME|all \\[mode]\n- sops, sops list, sops show NAME, sops sync NAME|all \\[mode]\n- skill NAME\n- experience add, list, show, search, prune\n- commands list, commands show NAME, commands reload\n- extensions list, show, install, enable, disable, uninstall, update\n- notes, notes clear\n- log, trajectory, plan\n- checkpoint, checkpoints, restore\n- quota\n- cron ... / cron dashboard\n- mcp, mcp start, mcp stop\n- files, files list\n- speech, tts\n\n准确行为以 [src/main.v](src/main.v) 的帮助文本和命令分发逻辑为准。\n\n补充说明：\n\n- `--enable-tools` 开启时，模型会收到已发现 skills 的元信息，并可通过 `activate_skill` 工具自行加载对应 skill。\n- `--auto-skills` 会显式鼓励模型优先自行选择匹配的 skill；若未设置 `workspace`，会默认使用当前目录以纳入项目级 `.agents/skills`。\n- 开启工具调用且存在全局 SOP 时，模型会先调用 `match_sop` 工具匹配最相关的 SOP。该工具会返回分项评分、命中层级以及 `suggested_read_order`，模型再按建议顺序用 `read_file` 读取对应 SOP；可通过 `auto_check_sops=false` 或环境变量 `MINIMAX_AUTO_CHECK_SOPS=0` 关闭。\n- `experience add` 默认会按 `knowledge_sync_mode` 自动同步到全局 `~/.config/minimax/skills` 和 `~/.config/minimax/sops`；可通过 `auto_write_skills`、`auto_upgrade_sops` 或对应环境变量关闭。\n- AI 开启工具调用后，还可以直接使用 `record_experience` 工具沉淀经验，不必依赖交互命令。\n\n## 文档索引\n\n- [docs/README.md](docs/README.md)：文档入口。\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)：系统结构和数据流。\n- [docs/IMPLEMENTATION.md](docs/IMPLEMENTATION.md)：源码模块职责映射。\n- [docs/EXTENSIBILITY.md](docs/EXTENSIBILITY.md)：MCP、技能、命令模板、扩展、经验库。\n- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)：开发、格式化、测试与排障约定。\n\n## 测试与验证\n\n```bash\nv test src/\n./tests/check_vfmt.sh\n./integration_test.sh\n./comprehensive_test.sh\n./tests/verify_speech_synthesis.sh [--with-api]\n./tests/verify_image_generation.sh [--with-api]\n```\n\n如果需要启用 Git hooks：\n\n```bash\nbash scripts/install-git-hooks.sh\n```\n\n当前 hooks 约定：\n\n- pre-commit 运行 tests/check\\_vfmt.sh\n- pre-push 运行 build.sh 和 v test src/\n\n语音合成验证脚本会从同一个 `~/.config/minimax/config` 读取 `api_key`，并用这把 key 依次验证多个模型的短文本合成与分段输出。\n\n图像生成验证脚本也会从同一个 `~/.config/minimax/config` 读取 `api_key`，并用这把 key 依次验证多个模型名；如果当前 token plan 不支持 `image-01-live`，脚本会明确跳过。\n\n## 前置依赖\n\n- V 编译器。\n- MCP 场景下需要对应工具运行时，例如 npx 或 uv。\n- Windows 上安装 uv 的常用方式：\n\n```powershell\nirm https://astral.sh/uv/install.ps1 | iex\nwinget install --id=astral-sh.uv -e\n```\n\n- 如果你在代理环境下安装，先为当前 PowerShell 会话设置 `HTTP_PROXY` 和 `HTTPS_PROXY`，例如 `http://127.0.0.1:7788`。\n- 如果使用 SQLite 经验库存储，系统中需要可用的 sqlite3。\n\n## 许可证\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhiter001%2Fminimax-v","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhiter001%2Fminimax-v","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhiter001%2Fminimax-v/lists"}