跨平台支持
AggRoot 支持在 Windows、Linux 和 macOS 上运行。本章介绍各平台的适配差异和配置要点。
平台支持
| 平台 | Shell 支持 | 状态 |
|---|---|---|
| Windows | Git Bash, PowerShell, CMD | 完全支持 |
| Linux | Bash, Zsh | 完全支持 |
| macOS | Zsh | 完全支持 |
Windows 配置
编码设置
Windows 默认使用 GBK 编码，可能导致中文乱码。启动前执行：
chcp 65001
这会将终端编码切换为 UTF-8。AggRoot 支持自动检测 GBK/UTF-8 编码并自动转换。
Shell 选择
通过 DEFAULT_SHELL 环境变量配置：
DEFAULT_SHELL=auto # 自动检测（推荐）
DEFAULT_SHELL=powershell # 使用 PowerShell
DEFAULT_SHELL=cmd # 使用 CMD
DEFAULT_SHELL=bash # 使用 Git Bash
DEFAULT_SHELL=nushell # 使用 Nushell
DEFAULT_SHELL=wsl # 使用 WSL
auto 模式会按以下顺序检测：PowerShell → CMD → Git Bash。
原生模块
AggRoot 依赖 better-sqlite3 和 sharp 等原生模块。这些模块都提供预编译二进制（prebuild），大多数情况下全局安装时会自动下载，无需本地编译：
npm install -g @aggroot-team/aggroot
如果预编译不可用，需要本地编译工具。请确保系统已安装：
- Windows: Visual Studio Build Tools（勾选 "C++ build tools"）
- Linux:
sudo apt-get install build-essential python3 - macOS:
xcode-select --install
然后重新全局安装即可。
路径分隔符
Windows 使用反斜杠 \，但 AggRoot 内部统一使用正斜杠 /：
// 正确 — 使用正斜杠
cd d:/Projects/my-app
// 错误 — 避免反斜杠
cd d:\Projects\my-app
Git Bash 会自动处理路径转换。
Linux 配置
系统依赖
确保安装了编译工具链（仅在原生模块预编译不可用时需要）：
# Ubuntu/Debian
sudo apt-get install build-essential python3
# CentOS/RHEL
sudo yum groupinstall "Development Tools"
sudo yum install python3
# Arch Linux
sudo pacman -S base-devel python3
权限问题
如果遇到 EACCES 权限错误：
# 不要使用 sudo npm install -g
# 改为修改 npm 全局目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
macOS 配置
系统依赖
使用 Homebrew 安装必要工具：
# 安装 Xcode Command Line Tools
xcode-select --install
# 安装 Python 3
brew install python3
原生模块
macOS 通常无需额外步骤，全局安装 AggRoot 时会自动下载预编译二进制：
npm install -g @aggroot-team/aggroot
如果预编译不可用，请确保已安装 Xcode Command Line Tools，然后重新全局安装。
文件系统大小写
macOS 默认文件系统不区分大小写。如果项目依赖大小写敏感的文件名（如 Git 仓库），建议创建大小写敏感的磁盘映像：
hdiutil create -size 20g -type SPARSE -fs "Case-sensitive APFS" -volname dev ~/dev.sparseimage
hdiutil mount ~/dev.sparseimage
# 挂载到 /Volumes/dev
编码处理
自动编码检测
AggRoot 在读取文件时自动检测编码：
| 平台 | 默认编码 | 检测策略 |
|---|---|---|
| Windows | GBK | 自动检测 BOM → UTF-8 → GBK |
| Linux | UTF-8 | 自动检测 BOM → UTF-8 |
| macOS | UTF-8 | 自动检测 BOM → UTF-8 |
编码转换
当检测到非 UTF-8 编码时，AggRoot 会自动转换为 UTF-8 处理，写入时保持原始编码。
原生模块
以下原生模块需要平台特定的编译（仅在预编译不可用时）：
| 模块 | 用途 | 编译要求 |
|---|---|---|
better-sqlite3 |
SQLite 数据库 | C++ 编译器, Python 3 |
sharp |
图像处理 | libvips, C++ 编译器 |
预编译二进制
better-sqlite3 和 sharp 都提供预编译二进制（prebuild），大多数情况下全局安装 AggRoot 时可以直接下载，无需本地编译。预编译不可用时才需要本地编译工具，安装后重新执行全局安装命令即可。
兼容性矩阵
| 功能 | Windows | Linux | macOS |
|---|---|---|---|
| 文件操作 | ✅ | ✅ | ✅ |
| Shell 执行 | ✅ (Git Bash / PowerShell) | ✅ | ✅ |
| 网络请求 | ✅ | ✅ | ✅ |
| Git 操作 | ✅ | ✅ | ✅ |
| 原生模块 | ✅ (需编译工具) | ✅ (需编译工具) | ✅ |
| 编码自动检测 | ✅ (GBK → UTF-8) | ✅ | ✅ |
| MCP 集成 | ✅ | ✅ | ✅ |
| 技能系统 | ✅ | ✅ | ✅ |
| 视觉分析 | ✅ | ✅ | ✅ |
| 路径处理 | ✅ (自动转换 \ → /) |
✅ | ✅ |
常见问题
Windows 上 Git 操作失败
确保安装了 Git for Windows，它包含 Git Bash 和必要的 Unix 工具。
# 检查 Git 是否可用
git --version
# 检查 Git Bash
where bash
中文输出乱码
- 执行
chcp 65001切换到 UTF-8 - 确保
.env文件使用 UTF-8 编码保存 - 终端字体选择支持中文的字体（如 JetBrains Mono、Cascadia Code）
Linux 上全局安装失败
- 确保安装了
build-essential和python3（仅在预编译不可用时需要） - 清除缓存后重试：
npm cache clean --force && npm install -g @aggroot-team/aggroot - 检查 Node.js 版本 >= 20.0.0：
node --version
macOS 上 sharp 安装失败
# 清除缓存
npm cache clean --force
# 使用 Homebrew 安装 libvips
brew install vips
# 重新全局安装
npm install -g @aggroot-team/aggroot
WSL 环境使用
AggRoot 可以在 WSL 中运行：
# 设置默认 Shell 为 WSL
DEFAULT_SHELL=wsl
# 或直接在 WSL 内运行
wsl
aggroot