MiniCode

MiniCode 是一个极简 AI 编码智能体，支持 OpenAI 兼容的 LLM 接口。

快速开始

uv sync
uv run minicode

命令行修复模式

MiniCode 可以作为外部评测框架调用的薄 agent，对指定仓库执行一次非交互修复：

minicode run --repo-dir <buggy_repo> --instruction <TASK.md> --max-rounds 5 --timeout 600

该模式会在 --repo-dir 内运行 agent，读取 --instruction 的任务说明，并将 agent 输出写到 stdout、工具调用摘要写到 stderr。run 模式默认不加载 MCP；如确实需要 MCP 工具，可显式加 --mcp。如果设置了 MINICODE_TRACE_PATH、MINI_SMITH_TRACE_PATH，或传入 --trace <path>，MiniCode 会把内部 message/tool-call/tool-result 事件写入 JSONL。测试执行、外层 trajectory、patch 和 summary 建议由外层 harness 统一收集。

模型配置

MiniCode 通过 OpenAI 兼容接口调用模型。本地模型和云端厂商模型使用同一套 OPENAI_* 配置，建议写在 .env 中：

OPENAI_MODEL=gpt-4o
OPENAI_BASE_URL=
OPENAI_API_KEY=sk-...
OPENAI_MAX_TOKENS=4096
OPENAI_TEMPERATURE=0
MINICODE_MAX_CONTEXT=128000
MINICODE_BACKEND=openai
MINICODE_AUTO_SAVE=true
MINICODE_SESSION_DIR=

本地 OpenAI 兼容服务（Ollama、vLLM、LM Studio、llama.cpp server 等）只需要把地址和模型名换掉：

OPENAI_MODEL=<local-model-name>
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_API_KEY=
OPENAI_MAX_TOKENS=2048
OPENAI_TEMPERATURE=0
MINICODE_MAX_CONTEXT=4096

云端兼容厂商同样使用这三个变量，例如 DeepSeek：

OPENAI_MODEL=deepseek-chat
OPENAI_BASE_URL=https://api.deepseek.com
OPENAI_API_KEY=sk-...

OPENAI_* 表示发给 OpenAI 兼容 API 的请求配置；MINICODE_* 只表示 MiniCode 自身运行配置。命令行参数 --model、--base-url、--api-key 只用于临时覆盖 .env。本地 localhost 服务通常不需要真实 API key，留空即可；如果你的本地服务启用了鉴权，再设置 OPENAI_API_KEY。

会话管理

Session 默认自动创建、自动记录、自动保存，不需要先执行任何 /task 命令。正常使用流程就是启动 MiniCode、直接交互，退出后第二天恢复最近会话：

uv run minicode
uv run minicode -r latest

交互模式仍提供少量显式管理命令：

/session       显示当前会话、Checkpoint 摘要和保存路径
/save [ID]     立即保存；传入 ID 时另存为指定会话
/resume ID     在当前 REPL 中恢复会话，支持 latest
/delete-session ID 删除指定会话
/sessions      列出最近保存的会话
/reset         清空当前对话历史

ID 表示实际会话 ID，例如 /resume session_20260614_212625_c2077cc7。REPL 也兼容 /resume <session_...> 和 /resume<session_...> 这类输入。

会话默认保存到 ~/.minicode/sessions，可用 MINICODE_AUTO_SAVE=false 关闭，或用 MINICODE_SESSION_DIR 指定目录。/save 是可选的即时检查点，不是启用会话功能的前置步骤。

Session Schema v4 将可恢复会话组织为四个核心部分：

messages：送入模型的用户、Assistant、工具消息，是当前会话上下文。
transcript：按顺序记录用户消息、工具调用与结果、压缩、子任务等运行事件。
checkpoint：当前目标、约束、计划、已完成工作、问题、下一步、验证结果及运行信息。
workspace_state：工作目录、仓库、分支、HEAD、修改/暂存/未跟踪文件和工作区指纹。

Checkpoint 不是直接把第一条用户消息当作目标。每轮 Assistant 完成后，MiniCode 会额外调用一次当前模型，根据旧 Checkpoint、最近对话和工具结果生成结构化摘要；问候和闲聊不会成为目标，用户明确切换任务时会更新目标。总结提示和结果不会写入 messages，只会在 Transcript 中记录 checkpoint_updated。如果模型调用或 JSON 解析失败，则使用不提升问候语的本地规则兜底，因此不会阻断正常对话和保存。该总结调用会产生额外的模型 token 和一次请求延迟。

其中 runtime、token_usage 收纳在 Checkpoint 中；工具事件、压缩和子任务收纳在 Transcript 中，不再以并列的顶层集合重复保存。旧版 Schema v1-v3 会在加载时自动迁移到 v4 结构。

Session 文件使用原子写入，进程中断时会保留上一份完整数据。Git 仓库存在未提交修改时，会在同一会话目录保存一个 .patch 参考副本；恢复不会自动应用 patch 或覆盖当前文件，而是校验目录、仓库、分支、HEAD 和工作区状态并显示差异警告。

每次保存都会更新 latest 指针，因此 uv run minicode -r latest 会恢复最近一次保存的会话。

MCP Web Search

MiniCode 可以作为 MCP client 接入 Exa，并暴露稳定的 web_search、web_fetch、code_search 工具。MCP 默认关闭；启用前可在 REPL 中运行 /mcp init 创建配置，或手动复制配置模板并配置 .minicode/mcp.json：

Copy-Item .minicode/mcp.example.json .minicode/mcp.json

MINICODE_MCP_ENABLED=true
MINICODE_MCP_CONFIG=.minicode/mcp.json
MINICODE_MCP_EXPOSE_RAW_TOOLS=false
EXA_API_KEY=...

{
  "servers": {
    "exa": {
      "enabled": true,
      "transport": "streamable_http",
      "url": "https://mcp.exa.ai/mcp?exaApiKey=${EXA_API_KEY}&tools=web_search_exa,web_fetch_exa",
      "timeout_seconds": 30
    }
  },
  "web_search": {
    "server": "exa",
    "tool": "web_search_exa",
    "max_results": 5
  },
  "web_fetch": {
    "server": "exa",
    "tool": "web_fetch_exa"
  },
  "code_search": {
    "server": "exa",
    "tool": "web_search_exa",
    "max_results": 5
  }
}

启动后使用 /mcp 查看 MCP server、transport、工具列表和最近错误；修改配置或环境变量后可使用 /mcp refresh 重新连接并刷新工具。默认只向模型暴露稳定工具；如需调试底层 MCP 原始工具，可设置 MINICODE_MCP_EXPOSE_RAW_TOOLS=true，这会额外暴露 mcp_<server>_<tool>。

FilesExpand file tree

README.md

Latest commit

History