mlx-code — 用于Apple Silicon的本地LLM编码代理

# mlx-code — 适用于 Apple Silicon 的本地 LLM 编码代理 来源：https://josefalbers.github.io/mlx-code/ Apple Silicon · MLX · 本地优先 ## 一款自带 LLM 的编码代理，**并能与一切工具对话**。 mlx-code 集成了 MLX 推理服务器、轻量级终端连接器、多协议 API 支持、git 工作树隔离以及可组合的多智能体基础组件——全部封装在一个 Python 包中。可离线运行，可接入 Shell 脚本，也可替换为任意外部 API。 ``` $ pip install mlx-code $ mlc ``` 需要 Python 3.11+ · Apple Silicon · mlx-lm 会自动安装 ## 工作原理 一个包，三个层次。MLX 服务器运行本地模型并支持所有主流 API 方言。连接器层决定由谁来驱动——内置 REPL 或外部工具（如 Claude Code）。工具在循环中调度，直到任务完成。 ### 连接器 — 内置 - 最小化终端 REPL，流式输出到 stdout - 可与 Shell 管道组合使用 - 支持 `/branch`、`/abort`、`/history` 等斜杠命令 - 除包本身外无其他依赖 ### 连接器 — 外部 (--leash) - Claude Code · Codex · Gemini CLI - 通过启动前设置 `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` / `GEMINI_BASE_URL`，将外部连接器路由到本地服务器 ### 连接器 — 库 Agent API - 直接导入 `Agent` - 可组合管道、分支并行工作器、从 git 提交恢复 - 库使用时无需服务器 ``` ↓ HTTP 或进程内 ↓ ``` ### 推理服务器 · main.py · 开箱即用 - MLX-LM 本地模型 + 多协议服务器 - 自带推理引擎，无需单独管理服务器进程 - 同一端口支持四种 API 方言： - OpenAI `/v1/chat/completions` - OpenAI `/v1/responses` - Anthropic `/v1/messages` - Gemini `generateContent` - DeepSeek ``` ↓ 令牌流 ↓ ↓ 工具调用调度 ↓ ``` ### 内置工具 (9) - `Read` · `Write` · `Edit` · `Bash` · `Grep` · `Find` · `Ls` · `Skill` · `Agent` ### 隔离性 - 每个会话从头创建一个新的 git 工作树（新分支） - 每次工具调用后自动提交 - 完整对话记录在提交信息中——可从任意检查点恢复 ### 可扩展性 - 子类化 `Tool` 并定义 Pydantic schema - 实例化时传入即可 - LSP、知识库和自定义数据库工具作为示例提供 ## 内部构成 ### 01 开箱即用的本地模型 - 以 `mlx-lm` 作为推理后端 - 下载任意 `mlx-community` 模型，`mlc` 立即可用——无需 Ollama、llama.cpp 或 API key ### 02 多协议 API 服务器 - 一个服务器，四种方言：OpenAI `/v1/chat/completions`、OpenAI `/v1/responses`、Anthropic `/v1/messages`、Gemini `generateContent` - 所有路由均支持 SSE 流式传输 ### 03 Shell 原生 REPL - 输出到 stdout - 非 TTY 时从 stdin 读取，天然适合管道组合 - 可在 Shell 中串联任务、重定向输出或构建多步骤工作流 ### 04 Git 工作树隔离 - 每个会话从干净的工作树开始（新分支） - 每次工具调用都会提交——同时保存文件状态和对话历史 - 出错了？你有完整的时间线可以调试或从任意点恢复 ### 05 多智能体管道 - 通过 `Agent` 工具或 `asyncio.gather` 生成子代理并行工作 - 上下文衰减是真实存在的问题——将子任务委派出去可以让各上下文保持聚焦 ### 06 可切换的连接器 - 使用内置 REPL 或 `--leash claude/codex/gemini` 将任何外部连接器指向你的本地模型 - 相同权重，不同前端——或者用 `mlc-run` 直接访问远程 API ## Shell 组合性 由于 `mlc` 在非 TTY 时从 stdin 读取，它像任何 Unix 工具一样工作。可以在任务间传递输出、重定向结果，甚至用单个命令串联多个智能体。 ```bash # 先请求解决方案，然后立即批判它 echo "Here's the solution: $(mlc -p "write a chrome extension to play YouTube at 5x speed") Now argue against it. What edge cases doesn't it handle?" | mlc # 研究智能体 → 提取智能体（通过管道） mlc -p "summarise BFT consensus into kb/draft.md" && \ mlc -p "read kb/draft.md, extract papers to kb/papers.json" # 指向远程 deepseek 模型而非本地 echo "explain lsp.py" | mlc-run --api deepseek --model deepseek-v3 # 串联两个远程端点：先解释，再规划 echo "explain lsp.py" | mlc-run -a deepseek | cat - PLAN.md | mlc-run --url http://localhost:9000 ``` ## 使用示例 ```bash # 安装并运行——本地 MLX 模型，内置 REPL pip install mlx-code mlc # 指定模型 mlc --model mlx-community/Qwen3.5-4B-OptiQ-4bit # 使用 Claude Code 作为连接器，本地模型作为大脑 mlc --leash claude --work ~/my-project # 限制可用工具，添加系统提示 mlc --tools Read Write Bash --system "You are a careful refactoring assistant." # 仅启动服务器——可从 curl 或自己脚本调用 mlc --leash none --port 8000 # mlc-run：仅使用连接器，无本地模型——指向任意端点 mlc-run --api claude mlc-run --api deepseek --model deepseek-v3 mlc-run --url http://192.168.1.5:8000 ``` ```python import asyncio from mlx_code.repl import Agent async def main(): # 简单单智能体 agent = Agent(system="You are a concise technical writer.") await agent.run( "Summarise all *.py files changed in the last 7 days. Save to digest.md." ) # 管道：研究者撰写，审阅者批判 researcher = Agent(system="You are a research assistant.") await researcher.run("Research PBFT. Save structured summary to kb/draft.md.") reviewer = Agent(system="You are a critical reviewer.") await reviewer.run( "Read kb/draft.md. Write a one-paragraph critique to kb/critique.md. " "Use ONLY information already in that file." ) asyncio.run(main()) ``` ```python import asyncio from mlx_code.repl import Agent async def main(): # 并行三个智能体，每个负责一个子主题 # 委派可保持上下文聚焦——避免上下文衰减 topics = ["history", "algorithms", "industry_usage"] agents = [Agent() for _ in topics] await asyncio.gather(*[ a.run(f"Research the {t} of Byzantine Fault Tolerance. Save to kb/{t}.md.") for a, t in zip(agents, topics) ]) # 单个合并者综合所有输出 reducer = Agent() await reducer.run("Read all files in kb/. Synthesise into final_report.md.") asyncio.run(main()) ``` ```python from mlx_code.tools import Tool from mlx_code.repl import Agent from pydantic import BaseModel, Field class QueryParams(BaseModel): query: str = Field(description="SQL query to run") class LiveDBTool(Tool): name = "QueryDB" description = "Execute a query against the dev database" parameters = QueryParams async def execute(self, params: QueryParams, signal=None) -> dict: result = run_query(params.query) return {"content": [{"type": "text", "text": result}], "is_error": False} # 实例化时传入 extra_tool_classes——无需全局注册 agent = Agent(extra_tool_classes=[LiveDBTool], tool_names=["QueryDB"]) ``` ```python import asyncio from mlx_code.gits import resume_worktree from mlx_code.repl import Agent, repl # 每次提交都将完整对话以 JSON 形式存储在提交信息中 # resume_worktree 可同时恢复文件状态和智能体记忆 async def main(): gwt, messages = resume_worktree(".", "abc1234") agent = Agent(ctx={"gwt": gwt}) agent.messages = messages await repl(agent) # 从断点处继续运行 asyncio.run(main()) ``` ## --leash 模式 `--leash` 标志决定运行哪个连接器来连接本地 MLX 服务器。使用 `mlc-run` 可跳过本地模型，直接连接远程提供商。 ### 本地模型 (mlc) — 连接器选项 | 模式 | 命令 | 说明 | |------|------|------| | 无 API / 默认 | `mlc` | 内置终端 REPL。输出到 stdout，非 TTY 时从 stdin 读取。 | | claude | `mlc --leash claude` | 启动 Claude Code，并将 `ANTHROPIC_BASE_URL` 指向本地服务器。 | | codex | `mlc --leash codex` | 通过生成的配置文件启动 Codex CLI，路由到本地 `/v1` 端点。 | | gemini | `mlc --leash gemini` | 启动 Gemini CLI，并将 `GOOGLE_GEMINI_BASE_URL` 设置为本地服务器。 | | none | `mlc --leash none` | 仅启动服务器——无连接器。请自带客户端或从 curl 调用。 | ### 无本地模型 (mlc-run) — 远程提供商 | 模式 | 命令 | 说明 | |------|------|------| | claude | `mlc-run --api claude` | 仅使用连接器，路由到 Anthropic 的 API。 | | gemini | `mlc-run --api gemini` | 仅使用连接器，路由到 Google Gemini。 | | deepseek | `mlc-run --api deepseek` | 仅使用连接器，路由到 DeepSeek。 | | 自定义 | `mlc-run --url http://...` | 任何兼容 OpenAI 的端点——另一台机器、虚拟机或云实例。 |