mu

# μ (mu) > AI 代理，具备完全的本地机器访问能力。可在主机系统上直接执行工具调用，并提供详细的步骤日志。 由 [Muse Mesh](https://github.com/muse-mesh) 构建。 ## 目录 - [快速开始](#快速开始) - [安装](#安装) - [本地（裸金属）](#本地裸金属) - [Docker](#docker) - [树莓派 / ARM64](#树莓派--arm64) - [配置](#配置) - [环境变量](#环境变量) - [配置文件](#配置文件) - [命令行标志](#命令行标志) - [使用](#使用) - [无头模式](#无头模式) - [交互式 REPL](#交互式-repl) - [Web UI](#web-ui) - [NDJSON 输出](#ndjson-输出) - [工具](#工具) - [权限模式](#权限模式) - [提供商兼容性](#提供商兼容性) - [MCP 集成](#mcp-集成) - [部署](#部署) - [Docker Desktop](#docker-desktop) - [树莓派（原生）](#树莓派原生) - [安全模型](#安全模型) - [审计日志](#审计日志) - [项目结构](#项目结构) - [开发](#开发) --- ## 快速开始 ```bash # 克隆并安装 git clone https://github.com/muse-mesh/mu.git && cd mu pnpm install # 配置 cp .env.example .env # 编辑 .env — 至少设置 MU_BOT_API_KEY # 交互式运行（CLI REPL） pnpm dev # 运行 Web UI pnpm dev -- --web # 打开 http://localhost:3141 ``` ## 安装 ### 要求 - **Node.js 22+** - **pnpm** （核心包管理，v10.30.1） ### 本地（裸金属） ```bash git clone https://github.com/muse-mesh/mu.git && cd mu corepack enable && corepack prepare pnpm@10.30.1 --activate pnpm install # 复制并配置环境 cp .env.example .env # 编辑 .env 文件，设置您的 API 密钥和模型设置 # 开发模式（tsx，热重载） pnpm dev # 生产构建 pnpm build pnpm start # CLI 模式 pnpm start:web # Web UI 模式 ``` ### Docker ```bash cd mu # 1. 配置环境（MU_BOT_API_KEY 是必填项） cp .env.example .env # 编辑 .env 文件，设置 MU_BOT_API_KEY，及 MU_BOT_API_BASE_URL 和 MU_BOT_MODEL（如果不是 OpenAI） # 2. 使用 docker compose 构建和启动（推荐） docker compose up -d --build # 3. 验证是否运行 docker ps --filter name=mu curl http://localhost:3141/api/health # → {"status":"ok","uptime":...,"model":"..."} ``` Web UI 可在 **http://localhost:3141** 访问。 查看日志：`docker logs -f mu` 停止：`docker compose down` **替代方案 — 无 compose 运行：** ```bash docker build -t mu:latest . docker run -d \ --name mu \ -p 3141:3141 \ --env-file .env \ -e MU_BOT_WEB_UI_ENABLED=true \ mu:latest ``` Docker 镜像： - 使用 `node:22-slim`，包含常见 CLI 工具（git, curl, wget, jq, ripgrep, tree, python3） - 以非 root 用户 `mu` 运行 - 应用程序代码位于 `/app`，为只读（属主 root） - 代理工作目录为 `/`，具有完全的文件系统读取权限 - 在 `/home/mu/.mu` 持久化数据（挂载卷以保留重启） - 健康检查在 `GET /api/health` ### 树莓派 / ARM64 对于资源受限的设备（1 GB RAM），原生运行而无需 Docker： ```bash # 在树莓派上 — 安装 Node.js 22 curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash - sudo apt-get install -y nodejs # 传输构建项目（从开发机器） # 在开发机器上： pnpm build rsync -avz --exclude node_modules --exclude .git . user@pi-ip:~/mu # 在树莓派上： cd ~/mu corepack enable && corepack prepare pnpm@10.30.1 --activate pnpm install --frozen-lockfile --prod # 配置 cp .env.example .env # 编辑 .env 文件 # 运行 MU_BOT_WEB_UI_ENABLED=true node dist/index.js --web # 访问 http://<pi-ip>:3141 ``` **可选**：创建 systemd 服务以自动启动： ```bash sudo tee /etc/systemd/system/mu.service > /dev/null << 'EOF' [Unit] Description=mu AI Agent After=network.target [Service] Type=simple User=pi WorkingDirectory=/home/pi/mu EnvironmentFile=/home/pi/mu/.env ExecStart=/usr/bin/node /home/pi/mu/dist/index.js --web Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target EOF sudo systemctl enable mu sudo systemctl start mu ``` --- ## 配置 配置从多个来源加载（优先级从高到低）： 1. **命令行标志** (`--model`, `--web`, 等) 2. **环境变量** (`MU_BOT_*`) 3. **配置文件** (`.mu.json` 在 cwd 或 `~/.mu.json`) 4. **默认值** ### 环境变量 复制 `.env.example` 到 `.env` 并自定义： | 变量 | 描述 | 默认值 | |----------|-------------|---------| | `MU_BOT_API_KEY` | LLM 提供商的 API 密钥 | — (**必填**) | | `MU_BOT_API_BASE_URL` | OpenAI 兼容的 API 端点 | `https://api.openai.com/v1` | | `MU_BOT_MODEL` | 模型标识符 | `gpt-4o` | | `MU_BOT_MAX_STEPS` | 每轮最大代理循环迭代次数 | `50` | | `MU_BOT_TEMPERATURE` | 采样温度（0–2） | `0` | | `MU_BOT_PERMISSION_MODE` | `auto`, `default`, `approve-destructive`, `plan` | `auto` | | `MU_BOT_WEB_UI_ENABLED` | 启用 Web UI 服务器 | `false` | | `MU_BOT_WEB_UI_PORT` | Web UI 端口 | `3141` | | `MU_BOT_LOG_LEVEL` | `quiet`, `normal`, `verbose`, `debug` | `verbose` | | `MU_BOT_LOG_DIR` | 审计日志目录 | `~/.mu/logs` | | `MU_BOT_LOG_TO_FILE` | 写入 JSONL 审计日志 | `true` | | `MU_BOT_OUTPUT_FORMAT` | CLI 输出：`text`, `json`, `ndjson` | `text` | | `MU_BOT_MAX_OUTPUT_LENGTH` | 截断工具输出长度 | `50000` | | `MU_BOT_COST_LIMIT_USD` | 每会话花费限制（0 = 无限制） | `0` | | `MU_BOT_SYSTEM_PROMPT` | 覆盖系统提示（内联） | 内置 | | `MU_BOT_SYSTEM_PROMPT_FILE` | 覆盖系统提示（来自文件） | — | | `MU_BOT_MCP_SERVERS` | MCP 服务器配置（JSON 数组） | — | ### 配置文件 在项目根目录或 `~/.mu.json` 中创建 `.mu.json`： ```json { "apiBaseUrl": "http://localhost:11434/v1", "model": "llama3", "maxSteps": 100, "permissionMode": "default" } ``` ### 命令行标志 ``` mu [prompt] [options] Options: -m, --model <model> 模型标识符 -b, --base-url <url> API 基地址 -k, --api-key <key> API 密钥 -s, --max-steps <n> 最大工具循环步骤 -v, --verbose 詳細输出 -d, --debug 调试输出 -w, --web 启用 Web UI -p, --port <port> Web UI 端口（默认：3141） --permission <mode> 权限模式 --output <format> 输出格式：text|json|ndjson --tools <tools> 以逗号分隔启用的工具列表 -c, --config <path> 配置文件路径 ``` --- ## 使用 ### 无头模式 传递一个参数作为提示 — mu 执行任务并退出： ```bash pnpm dev -- "列出当前目录中的文件" pnpm dev -- -m gpt-4o "解释此代码库" pnpm dev -- -s 5 "在 src/ 中查找所有 TODO 注释" pnpm dev -- --tools file_read,grep "在 src/ 中搜索导入" ``` ### 交互式 REPL 运行无提示以进行多轮对话： ```bash pnpm dev ``` ### Web UI 基于浏览器的界面，实时流式传输： ```bash pnpm dev -- --web # 打开 http://localhost:3141 ``` 功能： - 实时流式传输响应（AI SDK UI 协议） - 会话管理（创建、切换、恢复、删除） - 工具调用可视化，带有可折叠的详细面板 - Token 使用和成本跟踪 - 暗色/亮色主题切换 - 移动响应式布局，带有可折叠的侧边栏 ### NDJSON 输出 用于脚本的机器可读输出： ```bash pnpm dev -- --output ndjson "echo hello" | jq '.type' ``` --- ## 工具 mu 配备了 11 个内置工具： | 工具 | 描述 | 破坏性 | |------|-------------|:-----------:| | `shell_exec` | 执行 shell 命令 | ✓ | | `file_read` | 读取文件内容，可选的行范围 | | | `file_write` | 写入文件内容 | ✓ | | `file_edit` | 查找和替换编辑 | ✓ | | `glob` | 通过 glob 模式查找文件 | | | `grep` | 跨文件正则表达式搜索（使用 ripgrep，如果可用） | | | `list_dir` | 列出目录内容 | | | `http_fetch` | 获取 URL（GET, POST, 等） | | | `system_info` | 系统信息（OS, 架构, 内存等） | | | `think` | 思考草稿（无副作用） | | | `task_complete` | 信号任务完成 | | ### 工具过滤 ```bash # 只读探索 pnpm dev -- --tools file_read,grep,glob,list_dir "探索此代码库" # 仅限文件操作 pnpm dev -- --tools file_read,file_write,file_edit "重构配置模块" ``` ## 权限模式 | 模式 | 行为 | |------|----------| | `auto` | 所有工具在无需提示的情况下执行（默认） | | `default` | 只读自动批准；破坏性工具提示一次，然后记住 | | `approve-destructive` | 只读自动批准；每个破坏性调用都提示 | | `plan` | 仅允许只读工具；阻止破坏性工具 | ## 提供商兼容性 mu 与任何 OpenAI 兼容的 API 端点配合使用： ```bash # OpenAI MU_BOT_API_BASE_URL=https://api.openai.com/v1 MU_BOT_MODEL=gpt-4o # Ollama （本地） MU_BOT_API_BASE_URL=http://localhost:11434/v1 MU_BOT_MODEL=llama3 # OpenRouter MU_BOT_API_BASE_URL=https://openrouter.ai/api/v1 MU_BOT_MODEL=anthropic/claude-sonnet-4-20250514 # LM Studio MU_BOT_API_BASE_URL=http://localhost:1234/v1 MU_BOT_MODEL=local-model # Mume Gateway MU_BOT_API_BASE_URL=https://mume.ai/api/v1 MU_BOT_MODEL=z-ai/glm-5v-turbo ``` ## MCP 集成 连接外部 [MCP](https://modelcontextprotocol.io/) 服务器以获取额外工具： ```json { "mcpServers": [ { "name": "my-tools", "transport": "stdio", "config": { "command": "my-mcp-server", "args": [] } }, { "name": "remote", "transport": "sse", "config": { "url": "https://mcp.example.com/sse" } } ] } ``` 通过 `.mu.json` 或 `MU_BOT_MCP_SERVERS` 环境变量（JSON 字符串）设置。MCP 工具命名为 `mcp__{server}__{tool}`。 --- ## 部署 ### Docker Desktop ```bash cp .env.example .env # 配置 API 密钥和模型 docker compose up -d # 构建，在端口 3141 启动 docker compose logs -f # 监视日志 docker compose down # 停止 ``` ### 树莓派（原生） ```bash # 先决条件：Node.js 22，pnpm # 传输构建工件，安装生产依赖，运行 # 有关完整步骤，请参见“树莓派 / ARM64”下的安装部分 ``` ### 安全模型 当在 Docker 中部署时： - **应用程序代码** (`/app`) 由 `root:root` 拥有，权限为 `755` — 代理用户 (`mu`) 可以读取但 **无法修改其自己的代码** - **工作目录** 为 `/` — 代理可以浏览和读取整个文件系统 - **可写存储** 仅限于 `/home/mu/.mu` （日志，会话，内存） - **非 root 执行** — 容器以非特权用户 `mu` 运行 --- ## 审计日志 每个会话都会在 `~/.mu/logs/{sessionId}.jsonl` 处创建一个 JSONL 审计日志： ```bash # 查看最新日志 cat ~/.mu/logs/$(ls -t ~/.mu/logs/ | head -1) # 过滤工具调用 cat ~/.mu/logs/*.jsonl | jq 'select(.type == "tool_calls_start")' ``` 事件类型：`session_start`, `session_end`, `user_message`, `step_start`, `step_finish`, `tool_calls_start`, `tool_calls_finish`, `model_response`. --- ## 项目结构 ``` src/ ├── index.ts # CLI 入口点（Commander） ├── agent.ts # 代理循环（streamText + 工具） ├── config.ts # Zod 验证的配置加载器 ├── logger.ts # Pino 结构化日志记录器 + JSONL 审计 ├── state.ts # 反应性状态存储 ├── types.ts # 共享类型（MuToolDef, LogEvent 等） ├── shutdown.ts # 正常退出 SIGTERM/SIGINT ├── cost.ts # 具有模型定价的成本跟踪 ├── retry.ts # 具有指数退货的重试 ├── context.ts # 上下文窗口大小 + token 估计 ├── cli/ │ ├── renderer.ts # 终端输出格式化器 │ └── repl.ts # 交互式 REPL 模式 ├── compaction/ │ ├── index.ts # 上下文压缩管道 │ └── prompts.ts # 压缩和内存提取提示 ├── memory/ │ └── index.ts # 3 级内存系统（MEMORY.md，entries，会话） ├── tools/ │ ├── index.ts # 工具注册 + 执行管道 │ ├── build-tool.ts # buildTool() 工厂，具有安全默认值 │ ├── shell-exec.ts # Shell 命令执行 │ ├── file-read.ts # 文件读取，具有行范围 │ ├── file-write.ts # 文件写入 │ ├── file-edit.ts # 查找和替换编辑 │ ├── glob.ts # 文件 glob 匹配 │ ├── grep.ts # 正则表达式搜索（ripgrep + 回退） │ ├── list-dir.ts # 目录列表 │ ├── http-fetch.ts # HTTP 请求 │ ├── system-info.ts # 系统信息 │ ├── think.ts # 思考草稿 │ └── task-complete.ts # 任务完成信号 ├── permissions/ │ ├── index.ts # 4 模式权限系统 │ └── prompt.ts # CLI 权限提示 ├── mcp/ │ └── client.ts # MCP 服务器客户端 └── web/ ├── server.ts # Hono API 服务器 + 静态服务 └── sessions.ts # 会话存储（JSON 文件支持） web/ # React 前端（Vite） ├── src/ │ ├── App.tsx # 主应用组件（useChat 钩子） │ ├── main.tsx # React 入口点 │ └── app.css # 样式（暗色/亮色主题） ├── index.html └── vite.config.ts ``` ## 开发 ```bash # 开发模式（tsx，自动重载） pnpm dev # 启用 Web UI 的开发环境 pnpm dev -- --web # 前端开发服务器（热重载，代理到后端） pnpm dev:web # 类型检查 pnpm exec tsc --noEmit # 生产构建（前端 + 后端） pnpm build # 生产运行 pnpm start # CLI 模式 pnpm start:web # Web UI 模式（端口 3141） ``` ## License Apache 2.0 — 请参阅 [LICENSE](LICENSE) 以获取详细信息。 Copyright 2025 Muse Mesh.