NiumAgents-CLI

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

📦 安装

$3

bash

npm install -g niumagents-cli





🚀 使用方法



$3



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

bash

nium





$3



首次启动时，系统会自动创建

.nium/config.json

 配置文件。



配置示例（

.nium/config.json

）：

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



$3

bash

1. 启动CLI

nium



2. 开始一个任务（可以省略 /chat 命令）

nium> 帮我创建一个用户管理模块



或明确使用命令

nium> /chat 帮我创建一个用户管理模块



3. 如果任务中断，恢复会话

nium> /resume



4. 完成后清空会话

nium> /clear





📖 可用命令



$3



| 命令 | 说明 | 示例 |

|------|------|------|

|

| 开始新任务（默认命令） | 帮我实现登录功能

 |

|

/chat | 明确指定开始新任务 | /chat 创建API接口

 |

|

/resume | 恢复中断的会话 | /resume

 |

|

/clear | 归档并清空当前会话 | /clear

 |



$3



| 命令 | 说明 | 示例 |

|------|------|------|

|

/commit | 使用AI生成commit message并提交 | /commit

 |

|

/list_tools | 列出所有可用的工具（含MCP工具） | /list_tools

 |

|

/history | 查看归档的会话历史 | /history

 |



$3



| 命令 | 说明 | 示例 |

|------|------|------|

|

/help | 显示帮助信息 | /help

 |

|

/exit 或 /quit | 退出应用 | /exit

 |



$3



- 输入

 后可以使用模糊搜索来快速找到命令

- 支持命令简写和快速匹配



🎯 内置工具和智能体



$3



#### 思考和规划工具

-

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

 工具会根据运行平台自动启用。



$3



如果配置了 MCP 服务器，还可以使用额外的工具。通过

/list_tools

 命令可查看所有可用工具。



$3



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



#### 创建自定义智能体



在

.nium/agents/ 目录下创建 .md

 文件：

markdown

---

name: translator

description: 翻译助手，帮助翻译代码注释和文档

keywords: 翻译, translate, 中英文, translation

---



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



核心职责



1. 翻译代码注释（中文↔英文）

2. 翻译技术文档

3. 保持技术术语的准确性



工作流程



1. 读取需要翻译的文件

2. 识别需要翻译的内容

3. 进行准确的翻译

4. 保持格式和代码不变





⚙️ 配置



$3

.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                # 项目规则文件（可选）





$3



#### 环境变量（可选）



可以通过环境变量或

.nium/.env

 文件配置：

bash

启用上下文隔离模式（推荐）

USE_LLM_DISCLOSURE=true



启用LLM生成高质量摘要

USE_LLM_SUMMARY=true



启用调试模式

DEBUG=true





#### 项目规则文件（可选）



创建

.nium/rules.md

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



示例

.nium/rules.md：

markdown

项目规则



代码风格

- 使用 TypeScript 严格模式

- 使用 ES6+ 语法

- 优先使用函数式编程风格



命名约定

- 文件名使用 kebab-case

- 类名使用 PascalCase

- 函数和变量使用 camelCase



架构约定

- 遵循单一职责原则

- 保持模块解耦

- 使用依赖注入





$3



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



#### MCP 配置



在

.nium/config.json

 中配置 MCP 服务器：

json

{

  "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 工具。



🎨 使用示例



$3

bash

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

$3

bash

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

$3

bash

修改代码后

nium> /commit

AI会自动分析变更，生成合适的commit message并提交

$3

bash

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

$3

bash

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

✨ 核心特性

$3

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

$3

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

$3

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

$3

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

📝 许可证

MIT License - 详见 LICENSE 文件

🔗 相关链接

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

📦 安装

bash
npm install -g niumagents-cli

🚀 使用方法

$3

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

bash
nium

$3

首次启动时，系统会自动创建

配置文件。

配置示例（

）：

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 及兼容接口（如 DeepSeek, Qwen 等）
-

- Anthropic Claude API

$3

bash

1. 启动CLI

nium

2. 开始一个任务（可以省略 /chat 命令）

nium> 帮我创建一个用户管理模块

或明确使用命令

nium> /chat 帮我创建一个用户管理模块

3. 如果任务中断，恢复会话

nium> /resume

4. 完成后清空会话

nium> /clear

📖 可用命令

$3

| 命令 | 说明 | 示例 |
|------|------|------|
|

| 开始新任务（默认命令） | 帮我实现登录功能

 |

|

/chat | 明确指定开始新任务 | /chat 创建API接口

 |

|

/resume | 恢复中断的会话 | /resume

 |

|

/clear | 归档并清空当前会话 | /clear

 |



$3



| 命令 | 说明 | 示例 |

|------|------|------|

|

/commit | 使用AI生成commit message并提交 | /commit

 |

|

/list_tools | 列出所有可用的工具（含MCP工具） | /list_tools

 |

|

/history | 查看归档的会话历史 | /history

 |



$3



| 命令 | 说明 | 示例 |

|------|------|------|

|

/help | 显示帮助信息 | /help

 |

|

/exit 或 /quit | 退出应用 | /exit

 |



$3



- 输入

 后可以使用模糊搜索来快速找到命令

- 支持命令简写和快速匹配



🎯 内置工具和智能体



$3



#### 思考和规划工具

-

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

 工具会根据运行平台自动启用。



$3



如果配置了 MCP 服务器，还可以使用额外的工具。通过

/list_tools

 命令可查看所有可用工具。



$3



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



#### 创建自定义智能体



在

.nium/agents/ 目录下创建 .md

 文件：

markdown

---

name: translator

description: 翻译助手，帮助翻译代码注释和文档

keywords: 翻译, translate, 中英文, translation

---



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



核心职责



1. 翻译代码注释（中文↔英文）

2. 翻译技术文档

3. 保持技术术语的准确性



工作流程



1. 读取需要翻译的文件

2. 识别需要翻译的内容

3. 进行准确的翻译

4. 保持格式和代码不变





⚙️ 配置



$3

.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                # 项目规则文件（可选）





$3



#### 环境变量（可选）



可以通过环境变量或

.nium/.env

 文件配置：

bash

启用上下文隔离模式（推荐）

USE_LLM_DISCLOSURE=true



启用LLM生成高质量摘要

USE_LLM_SUMMARY=true



启用调试模式

DEBUG=true





#### 项目规则文件（可选）



创建

.nium/rules.md

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



示例

.nium/rules.md：

markdown

项目规则



代码风格

- 使用 TypeScript 严格模式

- 使用 ES6+ 语法

- 优先使用函数式编程风格



命名约定

- 文件名使用 kebab-case

- 类名使用 PascalCase

- 函数和变量使用 camelCase



架构约定

- 遵循单一职责原则

- 保持模块解耦

- 使用依赖注入





$3



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



#### MCP 配置



在

.nium/config.json

 中配置 MCP 服务器：

json

{

  "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 工具。



🎨 使用示例



$3

bash

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

$3

bash

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

$3

bash

修改代码后

nium> /commit

AI会自动分析变更，生成合适的commit message并提交

$3

bash

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

$3

bash

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

✨ 核心特性

$3

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

$3

📝 许可证

MIT License - 详见 LICENSE 文件

🔗 相关链接

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