Shell 工具
AggRoot 的 Shell 工具提供命令执行能力，是所有内置工具无法满足时的兜底方案。
Shell — 执行命令
在安全沙盒中执行 Shell 命令，支持跨平台环境检测和危险命令拦截。
参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| command | string | 是 | — | 要执行的 Shell 命令 |
| timeout | number | 否 | 120 | 超时秒数（最大 600） |
| cwd | string | 否 | 当前工作目录 | 命令执行目录 |
示例
// 安装依赖
Shell({"command": "npm install"})
// 运行构建
Shell({"command": "npm run build"})
// 带超时运行测试
Shell({"command": "npm test", "timeout": 300})
// 指定工作目录
Shell({"command": "python train.py", "cwd": "/projects/ml-model"})
跨平台 Shell 检测
Shell 工具根据操作系统自动选择最佳 Shell：
| 平台 | 首选 Shell | 回退 |
|---|---|---|
| Windows（有 Git Bash） | Git Bash | PowerShell |
| Windows（无 Git Bash） | PowerShell | — |
| Linux / macOS | 系统 Shell（/bin/bash） |
— |
Shell 配置
可通过环境变量 DEFAULT_SHELL 手动指定：
| 值 | 说明 |
|---|---|
auto |
自动检测（默认） |
bash |
使用 bash |
powershell |
使用 PowerShell |
gitbash |
使用 Git Bash |
安全机制
危险命令拦截
以下命令模式会被自动阻止：
| 模式 | 示例 | 原因 |
|---|---|---|
| 递归强制删除 | rm -rf /、rm -rf ~ |
数据丢失风险 |
| 磁盘写入 | mkfs、dd if= |
破坏性操作 |
| Fork 炸弹 | :(){ : |:& }; |
系统资源耗尽 |
| 网络管道执行 | curl ... | sh、wget ... | sh |
远程代码执行 |
| 权限修改 | chmod 777 /、sudo rm |
权限提升 |
| 系统文件覆写 | > /etc/passwd、> /etc/shadow |
系统安全 |
| 反弹 Shell | nc ... -e /bin/sh、/dev/tcp/ |
远程控制 |
| 系统控制 | shutdown、reboot、halt |
系统中断 |
| Shell 注入 | export VAR=$(...)、eval $var |
命令注入 |
其他安全措施
| 措施 | 说明 |
|---|---|
| 命令长度限制 | 最大 10000 字符 |
| Null 字节检查 | 阻止包含 \0 的命令 |
| 工作目录验证 | 阻止路径遍历和 Shell 元字符 |
| 环境变量隔离 | 过滤敏感变量，防止 API Key 泄漏 |
| 流式截断 | stdout/stderr 超过 20KB 后只保留尾部 8KB，防止 OOM |
| 超时保护 | 超时后完整终止进程组（含子进程树） |
| 进程隔离 | Windows 使用 taskkill /T /F，Linux/macOS 使用 kill -pgid |
使用原则
何时使用 Shell
| 场景 | 示例命令 |
|---|---|
| 安装/管理依赖 | npm install、pip install |
| 运行构建工具 | npm run build、cargo build |
| 执行测试 | npm test、pytest |
| 运行开发服务器 | npm run dev |
| 系统级操作 | 查看进程、端口、磁盘空间 |
| 使用专用 CLI | docker、kubectl、terraform |
何时不使用 Shell
| 操作 | 应使用 |
|---|---|
| 读取文件 | Read |
| 写入文件 | Write |
| 编辑文件 | Edit |
| 搜索文件名 | Glob |
| 搜索文件内容 | Grep |
| 查看目录结构 | DirectoryTree |
| Git 操作 | Git* 系列工具 |
专用工具比 Shell 命令更安全、输出格式更友好、且对 AI 更易解析。
输出处理
- stdout：命令的标准输出（截断到 8KB）
- stderr：命令的错误输出（截断到 8KB）
- exitCode：命令退出码
- summary：命令和退出码的简短摘要
- truncated：输出是否被截断
- duration：执行耗时（毫秒）
进度事件每秒更新一次，显示执行时间和输出预览。