🚀 Natural CLI：说人话！AI 驱动的智能命令行助手

🐧 Natural CLI

告别复杂的命令记忆，用自然语言与命令行交互

Natural CLI（Natural Command Line Interface）是一个基于Spring AI的智能命令行助手，通过自然语言生成和执行安全的命令行命令。让您用自然语言与命令行交互，无需记忆复杂的命令语法。

项目地址: gitee.com/neuxiang/na…

✨ 核心特性

🤖 AI 智能驱动

• 自然语言理解：直接描述需求，AI自动生成对应命令
• 多平台适配：根据系统类型自动生成对应平台的命令
• 智能决策：AI自动判断命令安全等级，分级处理

🔒 AI 三层安全机制

安全等级	判断标准	处理方式
🟢 安全只读	查询类命令，无系统风险	⚡ 直接执行，即时反馈
🟡 谨慎操作	写操作但风险可控	⏸️ 等待确认，用户授权后执行
🔴 危险操作	可能破坏系统或数据	❌ 直接拒绝，保障安全

🌐 友好界面

• Web界面：无需命令行经验，开箱即用
• 实时交互：流畅的聊天式交互体验
• 响应式设计：支持桌面和移动端访问

🛠️ 技术栈

技术领域	技术选型
后端框架	Spring Boot 3.4.4
AI集成	Spring AI 1.0.0
前端技术	HTML5 + CSS3 + JavaScript
构建工具	Maven
Java版本	17

🏗️ 系统架构

graph TB

subgraph "前端层 Frontend"

A[Web界面<br/>HTML/CSS/JS] --> B[用户交互<br/>自然语言输入]

end

subgraph "API网关层 API Gateway"

C[REST API<br/>Spring MVC] --> D[请求路由<br/>参数验证]

end

subgraph "业务逻辑层 Business Logic"

E[ShellChatService<br/>AI服务集成] --> F[命令生成<br/>安全评估]

F --> G[ShellExecutor<br/>命令执行]

end

subgraph "AI服务层 AI Service"

H[阿里云DashScope<br/>通义千问模型] --> I[自然语言理解<br/>命令生成]

end

subgraph "安全层 Security"

J[白名单机制<br/>allowed-commands] --> K[危险检测<br/>dangerous-commands]

K --> L[确认流程<br/>用户授权]

end

subgraph "数据层 Data"

M[配置文件<br/>application.yml] --> N[提示词模板<br/>system-prompt.md]

end

B --> C

D --> E

E --> H

G --> J

J --> L

N --> E

style A fill:#e1f5fe

style C fill:#f3e5f5

style E fill:#e8f5e8

style H fill:#fff3e0

style J fill:#ffebee

style M fill:#fafafa

📦 项目结构

src/
├── main/
│   ├── java/com/neuxiang/shell/
│   │   ├── controller/          # 控制器层
│   │   │   ├── ChatController.java     # 聊天API控制器
│   │   │   └── HomeController.java     # 主页控制器
│   │   ├── executor/            # 命令执行器
│   │   │   └── ShellExecutor.java      # 命令行执行核心逻辑
│   │   ├── service/             # 服务层
│   │   │   └── ShellChatService.java   # AI聊天服务
│   │   └── util/                # 工具类
│   │       ├── CommandDecisionParser.java  # 命令决策解析器
│   │       ├── PromptLoader.java        # 提示词加载器
│   │       └── SystemInfo.java          # 系统信息工具
│   └── resources/
│       ├── prompts/             # AI提示词
│       │   └── system-prompt.md         # 系统提示词
│       ├── static/              # 静态资源
│       │   ├── index.html               # 主页面
│       │   ├── script.js                # 前端逻辑
│       │   └── style.css                # 样式文件
│       └── application.yml              # 应用配置
└── test/
    └── java/com/neuxiang/shell/          # 测试代码
        ├── ShellChatServiceIntegrationTest.java  # 集成测试
        ├── ShellExecutorCoreTest.java           # 核心单元测试
        └── ShellExecutorTest.java               # 执行器测试

🚀 快速开始

环境要求

• Java 17+
• Maven 3.6+
• OpenAI API Key（或兼容的AI服务）

安装步骤

1. 克隆项目

    git clone https://gitee.com/neuxiang/natural-cli.git
    cd natural-cli
   

2. 配置AI服务

   项目已配置为使用环境变量 ALIYUN_API_KEY 来设置阿里云DashScope API密钥。

   方式一：设置环境变量后运行

   # Linux/macOS
   export ALIYUN_API_KEY=your-api-key
   mvn spring-boot:run
   
   # Windows (PowerShell)
   $env:ALIYUN_API_KEY="your-api-key"
   mvn spring-boot:run
   

   方式二：命令行直接传入

   # 运行JAR文件时传入环境变量
   ALIYUN_API_KEY=your-api-key java -jar target/shell-chat-1.0.0.jar
   
   # 或使用Maven运行时传入
   ALIYUN_API_KEY=your-api-key mvn spring-boot:run
   

   方式三：修改配置文件（不推荐）

   编辑 src/main/resources/application.yml，直接设置API密钥：

   spring:
     ai:
       openai:
         api-key: your-api-key
         base-url: https://dashscope.aliyuncs.com/compatible-mode
         chat:
           options:
             model: qwen-plus
             temperature: 0.7
   

3. 运行应用

   方式一：使用Maven运行（开发环境）

   # 设置环境变量后运行
   export ALIYUN_API_KEY=your-api-key
   mvn spring-boot:run
   
   # 或直接传入环境变量
   ALIYUN_API_KEY=your-api-key mvn spring-boot:run
   

   方式二：直接运行JAR文件（生产环境）

   # 设置环境变量后运行
   export ALIYUN_API_KEY=your-api-key
   java -jar target/shell-chat-1.0.0.jar
   
   # 或直接传入环境变量
   ALIYUN_API_KEY=your-api-key java -jar target/shell-chat-1.0.0.jar
   

4. 访问应用

   打开浏览器访问 http://localhost:8080

💡 使用示例

🟢 安全只读（AI 判断，直接执行）

用户输入	AI 生成命令	AI 决策
查看当前目录文件	ls	⚡ 直接执行
查看文件内容	cat filename.txt	⚡ 直接执行
查看内存使用情况	free -h	⚡ 直接执行
查看磁盘空间	df -h	⚡ 直接执行
查看运行进程	ps aux	⚡ 直接执行
搜索日志关键词	grep "error" app.log	⚡ 直接执行

🟡 谨慎操作（AI 判断，等待确认）

用户输入	AI 生成命令	AI 决策
删除某个文件	rm filename.txt	⏸️ 请确认后执行
创建新目录	mkdir new_folder	⏸️ 请确认后执行
修改文件权限	chmod 755 script.sh	⏸️ 请确认后执行

🔴 危险操作（AI 判断，直接拒绝）

用户输入	AI 识别风险	AI 决策
删除系统所有文件	rm -rf /	❌ 拒绝执行：危险操作
格式化磁盘	mkfs.ext4 /dev/sda	❌ 拒绝执行：破坏数据
强制关机	shutdown -h now	❌ 拒绝执行：影响服务
修改系统密码	passwd root	❌ 拒绝执行：权限敏感

🔐 安全配置说明

🛡️ 多层安全防护机制

Natural CLI 采用 四层安全防护 机制，确保命令执行的安全性：

1. 白名单机制（第一层防护）

# application.yml 配置
shell:
  allowed-commands: ipconfig,git,ls,cat,grep,ps,df,free,pwd,echo,head,tail,touch,rm,sleep,find

• 作用: 只允许执行配置的安全命令
• 保护: 防止执行未授权的命令
• 配置: 可根据实际需求自定义添加

2. 危险命令检测（第二层防护）

# application.yml 配置  
shell:
  dangerous-commands: rm,sudo,chmod,kill,mkfs,fdisk,dd,shutdown,reboot,halt,init

• 作用: 实时检测并阻止危险操作
• 保护: 防止系统破坏和数据丢失
• 配置: 包含常见危险命令，可扩展

3. AI 智能风险评估（第三层防护）

AI 模型基于以下因素评估命令风险：
- 命令类型（查询/修改/删除）
- 操作对象（文件/系统/网络）
- 执行权限（普通用户/管理员）
- 历史行为模式分析

4. 用户确认流程（第四层防护）

用户输入 → AI 生成命令 → 风险评估 → 用户确认 → 执行命令
                    ↓
                危险命令 → 直接拒绝

⚙️ 安全配置最佳实践

生产环境配置建议

shell:
  # 白名单：只开放必要的命令
  allowed-commands: ls,cat,grep,ps,df,free,pwd,echo,head,tail
  
  # 危险命令：严格限制
  dangerous-commands: rm,sudo,chmod,kill,mkfs,fdisk,dd,shutdown,reboot,halt,init
  
  # 执行限制
  timeout-seconds: 30          # 命令超时时间
  max-output-length: 5000      # 输出长度限制

开发环境配置建议

shell:
  # 白名单：开放更多命令用于测试
  allowed-commands: ipconfig,git,ls,cat,grep,ps,df,free,pwd,echo,head,tail,touch,rm,sleep,find
  
  # 危险命令：保持严格限制
  dangerous-commands: sudo,chmod,kill,mkfs,fdisk,dd,shutdown,reboot,halt,init
  
  # 执行限制相对宽松
  timeout-seconds: 60
  max-output-length: 10000

1. 访问应用

   打开浏览器访问 http://localhost:8080

⚙️ 配置说明

命令配置

在 application.yml 中配置支持的命令：

shell:
  allowed-commands: git,ls,cat,grep,ps,df,free,pwd,echo,head,tail,touch,rm
  dangerous-commands: rm,sudo,chmod,kill,mkfs,fdisk,dd,shutdown,reboot,halt,init
  timeout-seconds: 30
  max-output-length: 5000

安全机制

• 允许的命令: 白名单机制，只允许执行配置的命令
• 危险命令检测: 检测并阻止危险操作
• 确认机制: 危险命令需要用户确认
• 超时控制: 防止命令执行时间过长

🧪 测试

项目包含完整的测试套件：

# 运行所有测试
mvn test

# 运行特定测试类
mvn test -Dtest=ShellExecutorTest

测试覆盖

• ✅ 单元测试: 核心逻辑测试
• ✅ 集成测试: AI服务集成测试
• ✅ 功能测试: 完整业务流程测试

🔧 开发指南

添加新命令

1. 在 application.yml 的 allowed-commands 中添加新命令
2. 重启应用使配置生效
3. 前端会自动获取最新的命令列表

自定义AI模型

修改 application.yml 中的AI配置：

spring:
   ai:
     openai:
       api-key: your-new-api-key
       base-url: your-new-base-url
       chat:
         options:
           model: your-model-name
           temperature: 0.8

扩展功能

项目采用模块化设计，易于扩展：

• 添加新的命令类型: 扩展 ShellExecutor 类
• 自定义安全规则: 修改危险命令检测逻辑
• 增强UI功能: 修改前端JavaScript代码

📊 API接口

获取支持的命令列表

GET /api/chat/commands

响应示例

{
  "success": true,
  "data": {
    "response": "git,ls,cat,grep,ps,df,free,pwd,echo,head,tail,touch,rm"
  },
  "error": null
}

发送聊天消息

POST /api/chat/send
Content-Type: application/json

{
  "sessionId": "unique-session-id",
  "message": "查看当前目录文件"
}

确认执行命令

POST /api/chat/confirm
Content-Type: application/json

{
  "sessionId": "unique-session-id",
  "command": "ls -la"
}

🔒 安全特性

命令安全

• 白名单机制: 只允许执行配置的命令
• 危险检测: 实时检测危险命令模式
• 路径保护: 防止对关键系统路径的操作
• 超时控制: 限制命令执行时间

数据安全

• 输入验证: 所有用户输入都经过验证
• 输出限制: 限制命令输出长度
• 错误处理: 安全的错误信息返回

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

📄 许可证

本项目采用 Apache 2.0 许可证 - 查看 LICENSE 文件了解详情。

许可证摘要

Apache 2.0 许可证是一个宽松的开源许可证，允许您：

• ✅ 自由使用 - 商业和非商业用途
• ✅ 自由修改 - 修改源代码
• ✅ 自由分发 - 分发原始或修改后的版本
• ✅ 专利授权 - 包含专利授权条款

主要要求：

• 保留原始版权和许可声明
• 修改文件需要明确标注
• 包含NOTICE文件（如有）

完整的许可证条款请查看 LICENSE 文件。

🙏 致谢

• Spring Boot - 优秀的Java应用框架
• Spring AI - AI集成框架
• 阿里云 - AI模型服务提供商
• Gitee - 代码托管平台

📞 联系方式

如有问题或建议，请通过以下方式联系：

• 项目 Issues: Gitee Issues
• 邮箱: neuxiang@163.com

---

⭐ 如果这个项目对您有帮助，请给个星标支持！