# @aggroot-team/aggroot 中文文档

规范地址：https://npmcn.com/package/%40aggroot-team/aggroot/

版本：1\.13\.14
npm 元数据更新时间：2026-11-06T01:37:42.481Z
中文译文更新时间：2026-11-07T06:33:42.344Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aggroot-team/aggroot
原文对照：https://npmcn.com/package/%40aggroot-team/aggroot/?lang=original
源码仓库：https://gitcode.com/Mario_z/aita

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：21.5 MB，109 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.0\.0
- 运行依赖：39 个
- 首次发布：2026-05-28T14:36:23.009Z
- 最新版本发布：2026-11-06T01:37:42.314Z
- 近 30 天下载量：2036（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：71（近 12 个月 71 个）

## 中文简介

AggRoot - AI 助理(节点/节点脚本版本)

## 安装

```sh
npm install @aggroot-team/aggroot
```

也可以使用：`pnpm add @aggroot-team/aggroot`、`yarn add @aggroot-team/aggroot`、`bun add @aggroot-team/aggroot`

## README

# AggRoot - AI 编码助理

由Node.js和TypeScript所建的强大,可扩展的AI编码助手. 它提供文件操作,网页搜索,代码执行,Git集成,并更多通过现代DDD+插件架构提供.

[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://npmcn.com/package/%40aggroot-team/aggroot/LICENSE)

**[中文文档](https://npmcn.com/package/%40aggroot-team/aggroot/README_CN.md)**

## 目录

-   [核心特征](https://npmcn.com/package/%40aggroot-team/aggroot/#readme-core-features)
-   [CLI 接口](https://npmcn.com/package/%40aggroot-team/aggroot/#readme-cli-interface)
-   [快速启动](https://npmcn.com/package/%40aggroot-team/aggroot/#readme-quick-start)
-   [配置](https://npmcn.com/package/%40aggroot-team/aggroot/#readme-configuration)
-   [使用量](https://npmcn.com/package/%40aggroot-team/aggroot/#readme-usage)
-   [可用工具](https://npmcn.com/package/%40aggroot-team/aggroot/#readme-available-tools)
-   [技能系统](https://npmcn.com/package/%40aggroot-team/aggroot/#readme-skills-system)
-   [MCP 一体化](https://npmcn.com/package/%40aggroot-team/aggroot/#readme-mcp-integration)
-   [代理系统](https://npmcn.com/package/%40aggroot-team/aggroot/#readme-agent-system)
-   [内存管理](https://npmcn.com/package/%40aggroot-team/aggroot/#readme-memory-management)
-   [跨平台支持](https://npmcn.com/package/%40aggroot-team/aggroot/#readme-cross-platform-support)
-   [更改日志](https://npmcn.com/package/%40aggroot-team/aggroot/#readme-changelog)
-   [许可证](https://npmcn.com/package/%40aggroot-team/aggroot/#readme-license)

## 核心特征

-   **类型脚本第一**: 完整类型脚本支持,并有严格的类型检查和现代ES模块
-   **DDD + 插件结构**: 有可热插件的清洁域驱动设计
-   **可扩展工具系统**: 10个工具插件,提供30+内置工具,易于扩展
-   **多人工智能特工**: 密码代理、聊天代理和专门子代理
-   **智能内存**: 具有自动压缩和项目层面持久性的背景感记忆
-   **高级文件操作**: 读取、写取、编辑、Glob、Grep、目录 有智能页标和大纲模式的树
-   **Web 工具**: 有自动编码处理的Web搜索、Web获取和HTTP请求
-   **密码情报**: 执行、验证、格式、分析、重构和搜索代码符号
-   **Git 整合**: 具有跨平台支持的全基特操作
-   **库存引用**:实时股票报价和市场数据
-   **现代 CLI 界面**: 交互式终端 UI 有分屏布局和Markdown渲染
-   **技能系统**: 可重用的技能模板(解释、重构、测试、调试等)
-   **MCP 一体化**: 外部工具集成的示范背景协议
-   **安保管制**:内设风险控制,安全指挥执行,危险指挥拦截
-   **横线**: 在Windows、Linux和macOS上的无缝操作
-   **会话管理**: 具有历史、撤销和导出的多会支持
-   **YOLO 模式**: 切换自动执行模式以跳过工具确认提示

## CLI 接口

AggRoot 为现代终端UI提供了分屏布局:

```
┌──────────────────────────────────────────────────────────────┐
│                                                              │
│                     Output Area                              │
│              (scrollable conversation history)               │
│              (Markdown rendering support)                    │
│                                                              │
├──────────────────────────────────────────────────────────────┤  ← top separator
│ Agent> _                                                     │  ← input line
├──────────────────────────────────────────────────────────────┤  ← bottom separator
│ deepseek-chat | Token: 1234/5678 | Mode: coding             │  ← status bar
└──────────────────────────────────────────────────────────────┘
```

### CLI 特性

-   **分块布局**: 明确区分产出和输入区
-   **视觉分离器**: 双行分隔符明确标记输入区域
-   **状态栏**: 显示当前模型、 符号使用和工作模式
-   **思考动画**: AI处理过程中的动画状态显示
-   **原始模式输入**: 完整的键盘支持,包括箭头键和历史导航
-   **快速菜单**数字 :
    -   新闻 `/` 查看命令
    -   新闻 `$` 选择模型
    -   新闻 `#` 选择代理
    -   新闻 `@` 插入文件引用
-   **标记下渲染**: AI回复的丰富文本格式

### CLI 命令

| 命令 | 别名 | 说明 |
| --- | --- | --- |
| `/help` | `/h`, (中文(简体) ), `/?` | 显示帮助信息 |
| `/model <id>` | —— 说 | 切换AI 模式 |
| `/agents` | —— 说 | 列出所有可用的代理 |
| `/switch [n]` | —— 说 | 切换会话( 按次数) |
| `/reset` | —— 说 | 重置本届会议 |
| `/sessions` | —— 说 | 列出全部会话 |
| `/undo [path]` | —— 说 | 撤消文件更改 |
| `/memory` | —— 说 | 管理工程内存( 列表/ 添加/ 删除/ 搜索) |
| `/init` | —— 说 | 生成 AGGROOT.md 项目文件 |
| `/yolo` | —— 说 | 切换自动执行模式( skip 确认) |
| `/export [format]` | —— 说 | 导出对白 |
| `/config` | —— 说 | 显示当前配置 |
| `/history` | —— 说 | 显示命令历史 |
| `/clear` | `/cls` | 清除屏幕 |
| `/exit` | `/quit`, (中文(简体) ), `/q` | 退出程序 |

## 快速启动

### 先决条件

-   **节点.js** 页:1
-   AI 提供者 API 密钥( Deep Seek, OpenAI等)

### 安装

```bash
# Install globally via npm
npm install -g aggroot

# Run the assistant (CLI mode)
aggroot
```

### 网络网关模式

用内置前端启动网络网关服务器 :

```bash
# Start gateway (serves frontend + API on port 8642)
aggroot gateway

# Custom port and host
aggroot gateway --port 8080 --host 0.0.0.0

# Disable frontend static serving (API only)
aggroot gateway --no-static

# Custom static directory
aggroot gateway --static-dir /path/to/frontend/dist
```

| 终点 | 说明 |
| --- | --- |
| `http://localhost:8642` | 网络前端( SPA) |
| `http://localhost:8642/health` | 健康检查 |
| `http://localhost:8642/v1/chat/completions` | OpenAI 兼容聊天 API |
| `http://localhost:8642/v1/models` | 可用模式 |
| `ws://localhost:8642/ws` | WebSocket 聊天 |

## 配置

### 环境变量

创建一个 `.env` 文件直接在工程目录或设置环境变量中:

```env
# === AI Providers (at least one required) ===
DEEPSEEK_API_KEY=your_deepseek_api_key       # DeepSeek (default provider)
OPENAI_API_KEY=your_openai_api_key           # OpenAI GPT
CLAUDE_API_KEY=your_claude_api_key           # Anthropic Claude
ZHIPU_API_KEY=your_zhipu_api_key             # Zhipu AI
KIMI_API_KEY=your_kimi_api_key               # Kimi (Moonshot)
MINIMAX_API_KEY=your_minimax_api_key         # MiniMax

# === Ollama (Local Models) ===
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL_NAME=llama3.2

# === Shell Configuration ===
DEFAULT_SHELL=auto          # auto | powershell | cmd | bash | nushell | wsl
SHELL_TIMEOUT=30000         # Shell command timeout (ms)
CODE_EXECUTION_TIMEOUT=30   # Code execution timeout (seconds)

# === Session Management ===
MAX_SESSION_HISTORY=50       # Max messages per session
SESSION_TIMEOUT=60           # Session timeout (minutes)

# === Logging ===
LOG_LEVEL=info              # debug | info | warn | error | fatal

# === Security ===
SAFE_MODE=true              # Enable safe mode for code execution
DANGEROUS_COMMANDS=rm -rf,format,del /f /q,shutdown,reboot
```

> **重要内容:** 需要至少一个 AI 提供者 API 密钥 。 DeepSeek是默认的提供者.

## 使用量

### 交互式模式

开始AggRoot与AI助手互动:

```bash
aggroot
```

然后自然地输入您的问题或指示:

```
Agent> Read the README.md file and summarize it
Agent> Search for all TypeScript files in the src directory
Agent> Run the test suite and fix any failing tests
Agent> What's the current git status?
```

### 快速菜单

-   **`$`** — 打开模型选择菜单
-   **`#`** — 打开代理选择菜单
-   **`@`** - 插入文件引用
-   **`/`** — 显示命令列表

### YOLO 模式

启用 YOLO 模式无需确认即可自动执行工具 :

```
Agent> /yolo
✅ YOLO mode enabled - tools will auto-execute
```

### 会话管理

```bash
/sessions          # List all sessions
/switch 2          # Switch to session 2
/reset             # Reset current session
/export markdown   # Export conversation as Markdown
```

### 内存管理

```bash
/memory            # Show memory stats
/memory list       # List all project memories
/memory add        # Add a new memory
/memory search     # Search memories
```

## 可用工具

### 核心工具( E)`@aggroot/core-tools`(中文(简体) )

**文件操作 :**

| 工具 | 说明 |
| --- | --- |
| `Read` | 使用智能页、大纲模式和上下文搜索读取文件内容 |
| `Write` | 创建新文件或覆盖已有文件 |
| `Edit` | 精确文件编辑, 使用 diff 风格替换( 最小化符号消费) |
| `Glob` | 按名称/路径模式查找文件(例如, `**/*.ts`, (中文(简体) ), `src/**/*.py`(中文(简体) ) |
| `Grep` | 使用 regex 搜索文件内容( 查找代码的首选工具) |
| `DirectoryTree` | 快速列表目录树结构, 有可配置的深度和排除 |

**用户交互 :**

| 工具 | 说明 |
| --- | --- |
| `AskUser` | 用多选择或自由文本输入询问用户问题 |

**规划:**

| 工具 | 说明 |
| --- | --- |
| `EnterPlanMode` | 输入执行前分解复杂任务的计划模式 |
| `ExitPlanMode` | 退出计划模式并提交计划供批准 |

### 代码工具( E)`@aggroot/code-tools`(中文(简体) )

| 工具 | 说明 |
| --- | --- |
| `CodeExecute` | 安全执行 TypeScript/JavaScript 代码并带有超时控制 |
| `CodeValidate` | 用 TypeScript 编译器验证代码语法( 真实类型检查) |
| `CodeFormat` | 可缩进格式代码 |
| `CodeAnalyze` | 符号、复杂性、进出口和问题分析代码 |
| `CodeSearch` | 统一符号搜索(定义、参考、工作空间符号) |
| `CodeRefactor` | 代码重构操作( 摘录函数、 重命名、 组织导入) |

### Git 工具( R)`@aggroot/git-tools`(中文(简体) )

| 工具 | 说明 |
| --- | --- |
| `GitStatus` | 显示工作树状态 |
| `GitDiff` | 显示承诺之间或承诺与工作树之间的差异 |
| `GitLog` | 显示承诺日志 |
| `GitBranch` | 列出、创建或删除分支 |
| `GitShow` | 显示各类对象(承诺、标记、树等) |
| `GitAdd` | 阶段文件内容 |
| `GitCommit` | 记录寄存器的更改 |
| `GitPush` | 推入远程寄存器 |
| `GitPull` | 从远程寄存器中拉出 |
| `GitCheckout` | 切换分支或恢复工作树文件 |
| `GitRemote` | 管理远程仓库集 |
| `GitStash` | 污秽的工作目录中的 Stash 更改 |

### 网络工具( E)`@aggroot/web-tools`(中文(简体) )

| 工具 | 说明 |
| --- | --- |
| `WebSearch` | 搜索网络( 并优化查询) |
| `WebFetch` | 从 URL 获取网络内容( 自动重试并使用多个 URL) |
| `HttpRequest` | 制作 HTTP 请求( GET, POST, PUT, DELETETE, PATCH) |

### 贝壳工具( E)`@aggroot/shell-tools`(中文(简体) )

| 工具 | 说明 |
| --- | --- |
| `Shell` | 执行带有安全控制和超时的 shell 命令 |

> **重要内容:** 优先使用核心工具(read/write/edit/glob/grep)在 shell 命令之上进行文件操作. 仅用于核心工具无法完成的系统级操作.

### 待办工具( E)`@aggroot/todo-tools`(中文(简体) )

| 工具 | 说明 |
| --- | --- |
| `TodoCreate` | 创建新待办事宜项 |
| `TodoList` | 列出所有待办事宜 |
| `TodoUpdate` | 更新待办事宜 |
| `TodoDelete` | 删除待办事宜 |
| `TodoComplete` | 将待办事宜标为已完成 |

### 技能工具( E)`@aggroot/skill-tools`(中文(简体) )

| 工具 | 说明 |
| --- | --- |
| `Skill` | 按名称输入技能( 可重复使用的任务模板) |
| `ListSkills` | 列出所有可用的技能 |

### MCP 工具 (`@aggroot/mcp-tools`(中文(简体) )

| 工具 | 说明 |
| --- | --- |
| `MCP` | 连接外部工具服务器的示范背景协议集成 |

### 风险控制工具`@aggroot/risk-control-tools`(中文(简体) )

安全指挥执行和域名检查的安全和风险管理工具.

### 库存工具( E)`@aggroot/stock-tools`(中文(简体) )

| 工具 | 说明 |
| --- | --- |
| `StockQuote` | 获取实时股票报价 |

## 技能系统

AggRoot 包含一个内置技能系统,为共同任务提供可重复使用的模板:

**内建技能 :**

-   `explain` 解释代码或概念
-   `refactor` ——重构代码来提高质量
-   `test` - 生成测试案例
-   `document` 生成文件
-   `debug` 调试问题和错误
-   `analyze` ——分析密码库结构
-   `security-check` ——安全审计和脆弱性扫描
-   `commit` 生成有意义的承诺信息

**使用技能 :**

```
Agent> /explain this function
Agent> /refactor src/utils/helpers.ts
Agent> /test src/domain/agent/
```

## MCP 一体化

鼠标支持 **示范背景协议(MCP)** 用于整合外部工具服务器:

-   连接兼容 MCP 工具服务器
-   动态发现和使用外部工具
-   支助 **静态**, (中文(简体) ), **HTTP 密码**, (中文(简体) ), **网络安全套**,以及 **证监会** 运输协议
-   自动重联(带指数回放)和健康监测
-   在项目或用户级别配置 MCP 服务器

### 配置

MCP 服务器通过配置 `.aggroot/mcp.json` (项目一级)或 `~/.aggroot/mcp.json` (用户-全球):

```json
{
  "servers": [
    {
      "name": "powerpoint-server",
      "transport": {
        "type": "stdio",
        "command": "uvx",
        "args": ["--from", "office-powerpoint-mcp-server", "ppt_mcp_server"]
      },
      "enabled": true
    },
    {
      "name": "word-document-server",
      "transport": {
        "type": "stdio",
        "command": "uvx",
        "args": ["--from", "office-word-mcp-server", "word_mcp_server"]
      },
      "enabled": true
    }
  ],
  "settings": {
    "defaultTimeout": 30000,
    "autoReconnect": true
  }
}
```

### 预配置的 MCP 服务器

| 服务器 | 软件包 | 说明 |
| --- | --- | --- |
| `powerpoint-server` | `office-powerpoint-mcp-server` | 创建、编辑和操纵PowerPoint演示文稿(34个工具:图表、形状、表格、梯度等) |
| `word-document-server` | `office-word-mcp-server` | 创建、读取和操作Word文档(42个工具:段落、表格、图像、格式等) |

### 安装 MCP 服务器

```bash
# Option 1: Use uvx (recommended — no global install needed, requires uv/uvx)
# Already configured in mcp.json, just ensure uv/uvx is installed

# Option 2: Global pip install
pip install office-powerpoint-mcp-server office-word-mcp-server
```

> **说明:** 这个 `name` 在配置中决定工具前缀。 譬如说, `powerpoint-server` 生成工具如 `mcp_powerpoint-server_create_presentation`。 。 。 .

## 代理系统

AggRoot 具有强大的特性 **代理人** 具有多个专门代理人执行不同任务的系统:

### 内设特工

| 探员 | 名称 | 说明 |
| --- | --- | --- |
| 代码代理 | 代码代号 | 专业编码助理——指令重构,代码生成,多文件协作与子代理支持 |
| 内容代理 | 内容创建者 | 内容创建助理——文章、复制、专业PPT演示和Word文件(通过MCP) |
| 继续代理 | 恢复优化器 | 恢复优化专家——诊断,STAR重写,关键词分析,Word文档格式化(通过MCP) |
| 伴侣代理 | 小爱 | 温暖和关爱的虚拟伴侣——可爱和友好,支持网页搜索和文件操作 |
| 雷军助理 | 黎俊同学 | 黎俊风格的助手——投资见解,股票分析,业务战略 |
| 投资代理 | 投资大师 | 投资分析专家——由数据驱动的股票分析(A股和香港股票),引文/财务/技术/新闻 |
| 操作代理 | 操作主控器 | 系统业务专家——系统管理、环境管理、部署 |
| 风险控制代理 | 风险侦探 | 风险侦探——支付欺诈侦测,钓鱼侦测,域名,安全扫描 |

### 子代理系统

守则代理人可以将任务委托给专门的子代理人:

-   **探索代理**: 快速只读代码库探索,同时使用并行工具调用
-   **计划代理**: 计划和设计任务
-   **代码审查代理**守则审查和质量分析
-   **一般用途代理人**: 复杂的多步骤任务

子代理自动运行并返回完整输出,使任务能高效分解并平行执行.

## 内存管理

AggRoot 包括一个智能记忆系统:

-   **内存**: 在需要时自动跟踪自动压缩的对话上下文
-   **项目内存**: 跨会场持续的项目级内存
-   **内存命令**数字 : `/memory list`, (中文(简体) ), `/memory add`, (中文(简体) ), `/memory delete`, (中文(简体) ), `/memory search`
-   **自动压缩**: 明智地总结旧对话,以保持在符号限制之内
-   **文件跟踪**: 在与取消支持的对话中跟踪文件更改

## 跨平台支持

AggRoot 旨在在所有主要操作系统中无缝工作:

| 平台 | 建筑 | 贝壳支持 | 页:1 |
| --- | --- | --- | --- |
| **窗口** | x64, 武装64 | PowerShell, CMD, 吉特巴什, 努谢尔, WSL | 自动编码检测(GBK/UTF-8) |
| **链接** | x64, 武装64 | 巴什,兹什,鱼 | —— 说 |
| **马科斯** | x64, arm64 (苹果硅) | 兹什、巴什 | 原生苹果硅支持 |

### 平台兼容性

| 特性 | 窗口 | 链接 | 马科斯 |
| --- | --- | --- | --- |
| 文件操作 | ✅ | ✅ | ✅ |
| 贝壳命令 | (吉特·巴什/努谢尔/动力壳) | ✅ | ✅ |
| Web 工具 | ✅ | ✅ | ✅ |
| Git 整合 | ✅ | ✅ | ✅ |
| 编码支持 | (GBK/UTF-8) (中文(简体) ) | (UTF-8) (中文(简体) ) | (UTF-8) (中文(简体) ) |

## 更改日志

### 页:1

-   **菜单选择回声修复**: 从快速菜单中选择的命令(通过) `/`, (中文(简体) ), `$`, (中文(简体) ), `#`现在正确显示回声线(例如, `Code Deity ❯ /help`) 就像手动输入的命令
-   **`/clear` 命令修补**: 执行时去掉过多的空白行 `/clear` ——现在在不影响回溯历史的前提下适当清理可见区域
-   **多步骤输出修正**:多步输出命令中的固定空行问题(例如, `/upgrade`)在回声线被后续输出所覆盖的地方
-   **分层渲染改进**编号: `addOutput()` 要正确处理从输入回声到AI输出的过渡,防止文本重叠和光标定位出错

### 页:1

-   **努壳壳支持**: 已添加的 Nushell (中文(简体) )`nu`)作为Windows上支持的 shell,通过常见安装路径和PATH查询自动检测
-   **更新了 Shell 优先级**: Windows 上的默认 shell 优先级现在是 Git Bash > 努舍尔 > 动力壳
-   **智能贝壳语法**: 系统提示当前生成与检测到的默认 shell 兼容的 shell 语法, 而不是总是假设 Git Bash
-   **错误修正**数字 :
    -   自动读取工具更正 `../` 通过搜索FilePath回落的相对路径
    -   未输出时带有工具结果的 Asservative round
    -   Glob 工具描述仅澄清其匹配文件而非目录

## 许可证

这个项目根据麻省理工学院许可证获得许可证——见: [自由主义](https://npmcn.com/package/%40aggroot-team/aggroot/LICENSE) 详细文件.

## 常见问题

### @aggroot-team/aggroot 是什么？

AggRoot - AI 助理\(节点/节点脚本版本\)

### 如何安装 @aggroot-team/aggroot？

在项目目录运行 npm install @aggroot-team/aggroot，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 aggroot，可以用 npx aggroot 直接运行。

### @aggroot-team/aggroot 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/aggroot-team\_\_aggroot 是否存在。

### @aggroot-team/aggroot 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @aggroot-team/aggroot 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aggroot-team/aggroot 可以商用吗？

@aggroot-team/aggroot 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aggroot-team/aggroot 的下载量有多少？

根据 npm 官方下载统计，@aggroot-team/aggroot 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,036 次，日均约 68 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aggroot-team/aggroot 还在维护吗？

最新版本 1\.13\.14 发布于 2026/11/06（1 天前）；至今共发布 71 个版本，其中过去 12 个月发布了 71 个；首次发布于 2026/05/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。