MiniCode 是一个极简 AI 编码智能体，支持 OpenAI 兼容的 LLM 接口。
uv sync
uv run minicodeMiniCode 可以作为外部评测框架调用的薄 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 会恢复最近一次保存的会话。
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.jsonMINICODE_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>。