NiumAgents-CLI

一个基于 AI 的智能代码助手工具，支持多种编程语言的代码生成、项目分析、智能问答等功能。

📦 安装

全局安装

npm install -g niumagents-cli

🚀 使用方法

启动应用

全局安装后，可以直接使用：

nium

模型配置

首次启动时，系统会自动创建 .nium/config.json 配置文件。

配置示例（.nium/config.json）：

{
  "models": {
    "defaultModel": {
      "apiKey": "your-api-key-here",
      "baseURL": "https://api.openai.com/v1",
      "model": "gpt-4o",
      "provider": "openai", // openai(OpenAI兼容) / anthropic 
      "maxToken": 128000
    }
    // 可选：轻量级模型，用于简单任务和上下文压缩
    // "liteModel": {
    //   "apiKey": "your-api-key-here",
    //   "baseURL": "https://api.openai.com/v1",
    //   "model": "gpt-3.5-turbo",
    //   "provider": "openai",
    //   "maxToken": 16385
    // }
  }
}

支持的 provider 类型：

• openai - OpenAI 及兼容接口（如 DeepSeek, Qwen 等）
• anthropic - Anthropic Claude API

基本工作流程

# 1. 启动CLI
nium

# 2. 开始一个任务（可以省略 /chat 命令）
nium> 帮我创建一个用户管理模块

# 或明确使用命令
nium> /chat 帮我创建一个用户管理模块

# 3. 如果任务中断，恢复会话
nium> /resume

# 4. 完成后清空会话
nium> /clear

📖 可用命令

任务管理命令

| 命令 | 说明 | 示例 | |------|------|------| | <request> | 开始新任务（默认命令） | 帮我实现登录功能 | | /chat <request> | 明确指定开始新任务 | /chat 创建API接口 | | /resume | 恢复中断的会话 | /resume | | /clear | 归档并清空当前会话 | /clear |

开发辅助命令

| 命令 | 说明 | 示例 | |------|------|------| | /commit | 使用AI生成commit message并提交 | /commit | | /list_tools | 列出所有可用的工具（含MCP工具） | /list_tools | | /history | 查看归档的会话历史 | /history |

系统命令

| 命令 | 说明 | 示例 | |------|------|------| | /help | 显示帮助信息 | /help | | /exit 或 /quit | 退出应用 | /exit |

命令提示

• 输入 / 后可以使用模糊搜索来快速找到命令
• 支持命令简写和快速匹配

🎯 内置工具和智能体

核心工具

思考和规划工具

• think(thought) - 记录思考过程，支持结构化思维和推理
• plan(task, subtasks) - 创建和管理复杂任务计划
• todo(action, items) - 管理待办任务列表，跟踪任务进度
• askUser(question, options?) - 向用户提问并等待响应

文件操作工具

• read(path) - 读取文件内容
• write(path, content) - 写入文件（创建或覆盖）
• merge(path, content) - 智能合并内容到文件（使用三方合并算法，自动解决冲突）
• delete(path) - 删除文件或目录
• mkdir(path) - 创建目录
• move(source, destination) - 移动文件或目录
• copy(source, destination) - 复制文件或目录
• searchReplace(pattern, replacement, path) - 基于正则表达式的查找替换
• validate(path) - 验证文件语法和格式

搜索和检索工具

• glob(pattern) - 通过模式匹配文件（如 **/*.ts、src/**/*.java）
• grep(pattern, path) - 在文件中搜索内容（支持正则表达式）
• search_docs(query, scope?) - 在项目文档中搜索内容
• build_doc_index(paths?) - 构建项目文档索引
• search_file_changes(query?, options?) - 搜索和查询文件变更历史

项目探索工具

• quickProjectScan() - 快速扫描项目结构并生成文档（15-30秒）
• explore(topic, topicEnglish) - 深度探索项目整体架构、模块关系、设计模式（30-60秒）
• moduleExplore(moduleName, moduleEnglish, searchPattern?) - 深度探索单个模块的内部实现、函数细节（60-120秒）
• toolingExplore(topic, topicEnglish) - 深度探索构建工具和开发流程配置（30-60秒）

智能辅助工具

• smartSuggest(context, options?) - 基于上下文的智能建议和推荐

系统工具

• shell(command) - 执行通用 shell 命令（跨平台）
• bash(command) - 执行 Bash 命令（Linux/macOS）
• powershell(command) - 执行 PowerShell 命令（Windows）

注意： bash 和 powershell 工具会根据运行平台自动启用。

MCP 工具（可选）

如果配置了 MCP 服务器，还可以使用额外的工具。通过 /list_tools 命令可查看所有可用工具。

自定义智能体

你可以创建自己的智能体来处理特定任务。

创建自定义智能体

在 .nium/agents/ 目录下创建 .md 文件：

---
name: translator
description: 翻译助手，帮助翻译代码注释和文档
keywords: 翻译, translate, 中英文, translation
---

你是一位翻译助手。你的任务是帮助翻译代码注释、文档和技术文本。

## 核心职责

1. 翻译代码注释（中文↔英文）
2. 翻译技术文档
3. 保持技术术语的准确性

## 工作流程

1. 读取需要翻译的文件
2. 识别需要翻译的内容
3. 进行准确的翻译
4. 保持格式和代码不变

⚙️ 配置

.nium 目录结构

.nium/ 目录包含所有配置文件和会话数据，该目录已自动添加到 .gitignore。

.nium/
├── config.json             # 全局配置（模型、MCP服务器等）
├── session.jsonl           # 当前会话数据（用于恢复）
├── agents/                 # 自定义智能体配置 ⭐
│   ├── commit-helper.md
│   ├── translator.md
│   └── your-agent.md
├── archives/               # 历史会话归档
│   └── session-*.jsonl
├── project/                # 项目信息缓存
│   └── project.json
└── rules.md                # 项目规则文件（可选）

高级配置

环境变量（可选）

可以通过环境变量或 .nium/.env 文件配置：

# 启用上下文隔离模式（推荐）
USE_LLM_DISCLOSURE=true

# 启用LLM生成高质量摘要
USE_LLM_SUMMARY=true

# 启用调试模式
DEBUG=true

项目规则文件（可选）

创建 .nium/rules.md 文件来定义项目特定的规则和约定。该文件用于告诉AI助手项目的编码规范、架构约定、开发流程等信息。

示例 .nium/rules.md：

# 项目规则

## 代码风格
- 使用 TypeScript 严格模式
- 使用 ES6+ 语法
- 优先使用函数式编程风格

## 命名约定
- 文件名使用 kebab-case
- 类名使用 PascalCase
- 函数和变量使用 camelCase

## 架构约定
- 遵循单一职责原则
- 保持模块解耦
- 使用依赖注入

MCP 集成

支持 Model Context Protocol (MCP)，可以通过MCP服务器扩展更多功能。

MCP 配置

在 .nium/config.json 中配置 MCP 服务器：

{
  "models": {
    "defaultModel": {
      "apiKey": "your-api-key-here",
      "baseURL": "https://api.openai.com/v1",
      "model": "gpt-4o",
      "provider": "openai",
      "maxToken": 128000
    }
  },
  "mcpServers": [
    {
      "name": "example-http-server",
      "description": "示例 HTTP MCP 服务器",
      "transport": "http",
      "url": "http://localhost:3000",
      "headers": {
        "Authorization": "Bearer your-token-here"
      },
      "timeout": 30000,
      "enabled": false
    }
  ]
}

配置说明：

• name - 服务器名称（唯一标识）
• description - 服务器描述
• transport - 传输协议（http 或 stdio）
• url - 服务器地址（HTTP 模式）
• headers - 请求头（可选）
• timeout - 超时时间（毫秒）
• enabled - 是否启用

配置完成后重新启动，使用 /list_tools 命令查看可用的 MCP 工具。

🎨 使用示例

示例1：创建新功能

nium> 帮我创建一个用户认证模块，包括登录、注册和token验证

示例2：代码分析和重构

nium> 分析 src/api/user.ts 文件，找出潜在问题并优化代码

示例3：自动提交代码

# 修改代码后
nium> /commit
# AI会自动分析变更，生成合适的commit message并提交

示例4：项目探索

nium> 探索这个项目的结构，告诉我主要的模块和它们的功能

示例5：智能问答

nium> 这个项目中的用户认证是如何实现的？

✨ 核心特性

智能上下文管理

• 自动上下文压缩 - 使用 LLM 智能压缩历史对话，保持上下文相关性
• 语义分析 - 自动分析代码语义，提取关键信息
• 上下文锚点 - 标记重要上下文，避免信息丢失
• 会话恢复 - 支持中断恢复，保持工作连续性
• 项目语言缓存 - 自动检测和缓存项目语言，优化后续操作

智能文件操作

• 文件变更追踪 - 自动记录所有文件变更，支持历史查询
• 编码自动检测 - 智能识别文件编码（UTF-8/GBK等）

项目分析能力

• 快速扫描 - 快速分析项目结构，生成文档（15-30秒）
• 深度探索 - 深入分析项目架构、模块关系、设计模式（30-60秒）
• 模块探索 - 探索单个模块的内部实现和调用链（60-120秒）
• 依赖分析 - 分析项目依赖关系（支持 Java Maven/Gradle、npm、pip 等）
• 代码标准检测 - 自动检测项目使用的代码规范和工具
• 文档搜索 - 基于 FlexSearch 的文档全文检索

ReAct 智能体架构

基于 ReAct（Reasoning + Acting）模式：

1. Thought（思考） - 结构化思考和推理过程
2. Action（行动） - 执行具体操作和工具调用
3. Observation（观察） - 观察执行结果和反馈
4. 循环优化 - 根据结果调整策略，持续改进

📝 许可证

MIT License - 详见 LICENSE 文件

🔗 相关链接

• GitHub 仓库
• 问题反馈
• 更新日志