AggRoot - AI 编码助理

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

中文文档

目录

• 核心特征
• CLI 接口
• 快速启动
• 配置
• 使用量
• 可用工具
• 技能系统
• MCP 一体化
• 代理系统
• 内存管理
• 跨平台支持
• 更改日志
• 许可证

核心特征

• 类型脚本第一: 完整类型脚本支持,并有严格的类型检查和现代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 命令

快速启动

先决条件

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

安装

# Install globally via npm
npm install -g aggroot

# Run the assistant (CLI mode)
aggroot

网络网关模式

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

# 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

配置

环境变量

创建一个 .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助手互动:

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

会话管理

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

内存管理

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

可用工具

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

文件操作 :

用户交互 :

规划:

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

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

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

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

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

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

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

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

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

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

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

技能系统

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 (用户-全球):

{
  "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 服务器

安装 MCP 服务器

# 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 具有强大的特性 代理人 具有多个专门代理人执行不同任务的系统:

内设特工

子代理系统

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

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

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

内存管理

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

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

跨平台支持

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

平台兼容性

更改日志

页: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 工具描述仅澄清其匹配文件而非目录

许可证

这个项目根据麻省理工学院许可证获得许可证——见: 自由主义 详细文件.