安装与配置

AggRoot 是基于 Node.js 的 AI 编程助手。本文档介绍如何安装、配置并启动 AggRoot。

环境要求

依赖	最低版本	说明
Node.js	>= 20.0.0	推荐使用 LTS 版本
npm	随 Node.js 安装	包管理器
Git	任意稳定版	用于 Git 工具和项目操作

Tips: 使用 node -v 检查 Node.js 版本。如需管理多版本，推荐使用 nvm（Linux/macOS）或 nvm-windows（Windows）。

安装

全局安装（推荐）

npm install -g @aggroot-team/aggroot

安装完成后，在任意目录直接运行：

aggroot

免安装运行

npx @aggroot-team/aggroot

临时执行，不污染全局环境。

API 密钥配置

AggRoot 支持多种 AI 模型提供商，至少需要配置一个 API 密钥。

配置步骤

复制环境变量模板：
```
cp .env.example .env
```
编辑 .env 文件，填入你的 API 密钥。

支持的模型提供商

提供商	环境变量	默认 API 地址	说明
DeepSeek	`DEEPSEEK_API_KEY`	`https://api.deepseek.com/v1`	DeepSeek V4 系列，默认提供商，推荐
智谱 AI	`ZHIPU_API_KEY`	`https://open.bigmodel.cn/api/paas/v4`	GLM-5.2 / GLM-5.1 / GLM-4.7 系列
通义千问	`QWEN_API_KEY` 或 `DASHSCOPE_API_KEY`	`https://dashscope.aliyuncs.com/compatible-mode/v1`	Qwen3.7 / Qwen3.6 系列
Kimi (月之暗面)	`KIMI_API_KEY`	`https://api.moonshot.cn/v1`	Kimi K2.7 Code / K2.6 系列
Claude	`CLAUDE_API_KEY`	`https://api.anthropic.com/v1`	Claude Fable 5 / Opus 4.8 / Sonnet 4.6
OpenAI	`OPENAI_API_KEY`	`https://api.openai.com/v1`	GPT-5.5 / GPT-5.4 系列
MiniMax	`MINIMAX_API_KEY`	`https://api.minimaxi.com/v1`	MiniMax M3 / M2.7 系列
小米 MiMo	`MIMO_API_KEY`	`https://api.xiaomimimo.com/v1`	MiMo V2.5 系列
NVIDIA NIM	`NVIDIA_API_KEY`	`https://integrate.api.nvidia.com/v1`	聚合多家模型，支持按模型配密钥
SiliconFlow	无需密钥	`https://api.siliconflow.cn/v1`	免费开源模型，开箱即用
Ollama (本地)	无需密钥	`http://localhost:11434`	本地部署，免费

Tips: 最低要求是配置 DEEPSEEK_API_KEY 或 OPENAI_API_KEY。SiliconFlow 提供免费模型，无需 API 密钥即可使用。如果使用 Ollama 本地模型，只需确保 Ollama 服务已启动。

NVIDIA NIM 按模型配置密钥

NVIDIA NIM 支持为不同模型设置独立的 API 密钥：

# 全局密钥
NVIDIA_API_KEY=nvapi-xxxx
NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1

# 按模型覆盖（模型 ID 中的 / 和 . 替换为 _，全部大写）
NVIDIA_API_KEY_Z_AI_GLM_51=nvapi-xxxx
NVIDIA_API_KEY_DEEPSEEK_AI_DEEPSEEK_R1=nvapi-xxxx

Shell 配置

# 默认 Shell（auto 为平台默认：Windows 用 PowerShell，Linux/Mac 用 bash）
# 可选: auto, powershell, cmd, bash, nushell, wsl
DEFAULT_SHELL=nushell

# Shell 命令执行超时（毫秒）
SHELL_TIMEOUT=30000

# 代码执行超时（秒）
CODE_EXECUTION_TIMEOUT=30

Tips: 在 Windows 上推荐使用 nushell 或 powershell。如果需要执行 Linux 命令，可配置为 wsl。

安全配置

# 安全模式（true 时禁止执行高风险命令）
SAFE_MODE=true

# 危险命令黑名单（逗号分隔）
DANGEROUS_COMMANDS=rm -rf,format,del /f /q,shutdown,reboot

Tips: 生产环境中建议保持 SAFE_MODE=true。代理系统会根据风险等级自动审批或拦截命令。

视觉服务配置（图片理解）

AggRoot 支持图片理解能力，通过视觉模型分析图片内容。

# 启用视觉服务
VISION_ENABLED=true

# 视觉 API 端点（OpenAI 兼容）
# SiliconFlow: https://api.siliconflow.cn/v1
# DashScope:   https://dashscope.aliyuncs.com/compatible-mode/v1
# vLLM 本地:   http://localhost:6000/v1
VISION_ENDPOINT=https://api.siliconflow.cn/v1

# 视觉 API 密钥
VISION_API_KEY=your_vision_api_key

# 视觉模型名称
VISION_MODEL=Qwen/Qwen3-VL-8B-Instruct

启用后，你可以在对话中让 AggRoot 分析截图、图片等视觉内容。

启动

aggroot

看到交互式提示符即表示启动成功。输入 /exit 退出。

常见问题

Windows 中文乱码

解决方案:

# 在 CMD 中设置 UTF-8 编码
chcp 65001

或使用 Windows Terminal，在设置中将编码设为 UTF-8。

依赖安装网络超时

解决方案:

# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com

内存不足

解决方案:

# 增大 Node.js 堆内存（已在 .env 中配置）
NODE_OPTIONS=--max-old-space-size=4096

原生模块加载失败

症状: 启动时报 better-sqlite3 或 sharp 模块错误。

解决方案: 重新全局安装 AggRoot，安装过程会自动下载预编译二进制：

npm install -g @aggroot-team/aggroot

better-sqlite3 和 sharp 都提供预编译二进制（prebuild），大多数情况下安装时可以直接下载，无需本地编译。如果仍然失败，请确保系统已安装所需的运行时依赖：

Windows: 安装 Visual Studio Build Tools，确保勾选 "C++ build tools"
Linux: sudo apt install build-essential python3 make g++
macOS: xcode-select --install

快速上手