# ExCLI - Agent CLI 框架

一个具有更好记忆能力、输出能力和工具使用能力的 Agent CLI 框架。

## 项目目标

这个 Agent CLI 解决什么问题：
- 更智能的上下文理解：通过短期和长期记忆记住用户偏好和项目背景
- 结构化输出：根据任务类型自动选择最佳输出风格
- 高效工具集成：通过统一的工具接口完成文件、搜索、执行等任务

适合场景：
- 个人 AI 助手
- 代码开发和调试
- 文档查询和管理
- 自动化任务执行

核心能力：
- 记忆系统：自动提取和检索长期记忆
- 输出风格：自动判断简洁/详细/技术型/写作型
- 工具调用：智能选择和执行工具

## 技术选型

- 语言：Node.js 18+
- CLI：原生 readline + Chalk + Ora
- 数据存储：JSON 文件存储
- 模型调用：OpenAI API (兼容任何 OpenAI 兼容 API)
- 日志：Pino
- 配置：环境变量 + .env

## 安装

```bash
# 克隆项目
cd excli

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 配置 OPENAI_API_KEY
```

## 使用

```bash
# 直接运行
node bin/cli.js

# 或使用启动脚本
chmod +x start.sh
./start.sh
```

## CLI 命令

- `help` - 显示帮助
- `clear` - 清屏
- `memory` - 查看记忆状态
- `preferences` - 查看用户偏好
- `tools` - 查看可用工具
- `stats` - 查看统计信息
- `quit/exit` - 退出

## 项目结构

```
excli/
├── bin/
│   └── cli.js           # CLI 入口
├── src/
│   ├── index.js        # 主程序入口
│   ├── config/        # 配置模块
│   ├── core/          # 核心模块
│   │   ├── agent.js   # Agent 主循环
│   │   └── model.js  # 模型适配层
│   ├── memory/       # 记忆模块
│   ├── prompts/     # Prompt 模板
│   ├── tools/       # 工具模块
│   └── utils/       # 工具函数
├── data/             # 数据目录
│   ├── memory/       # 长期记忆
│   └── sessions/    # 会话数据
├── logs/             # 日志目录
├── bin/               # 可执行脚本
├── package.json
└── .env.example
```

## 功能说明

### 记忆系统

- **短期记忆**：保存当前会话上下文，包含用户输入、助手输出、工具结果
- **长期记忆**：JSON 文件持久化存储，区分敏感信息，自动提取
- **记忆提取**：每隔 N 轮对话自动提取重要信息

### 工具系统

- `read_file` - 读取文件
- `write_file` - 写入文件
- `list_files` - 列出文件
- `run_shell` - 执行命令
- `search_text` - 搜索文本

### 输出风格

根据任务类型自动选择：
- 简洁模式：简短回答
- 详细模式：完整解释
- 技术型：代码和命令
- 写作型：文档和说明

## 配置

主要环境变量：
- `OPENAI_API_KEY` - OpenAI API 密钥
- `OPENAI_BASE_URL` - API 地址（默认 OpenAI）
- `OPENAI_MODEL` - 模型名称
- `AGENT_TEMPERATURE` - 温度参数
- `MEMORY_DB_PATH` - 记忆数据库路径
- `LOG_LEVEL` - 日志级别

## 扩展

### 添加新工具

在 `src/tools/index.js` 添加新的工具类：

```javascript
export class MyTool extends BaseTool {
  constructor() {
    super('my_tool', '工具描述', {
      // JSON Schema
    });
  }
  
  async execute(args) {
    // 实现逻辑
    return { success: true, result: '...' };
  }
}
```

### 修改 System Prompt

在 `src/prompts/index.js` 修改 `SYSTEM_PROMPT`。

## 示例

运行示例：

```
$ ./start.sh
欢迎使用 ExCLI！你可以用自然语言和 AI 交互，输入 help 查看命令帮助。

excli> 帮助
# 显示帮助...

excli> 列出当前目录的 js 文件
# AI 处理并返回结果...

excli> memory
# 显示当前记忆状态...

excli> quit
再见！
```

## 注意事项

1. 首次运行需要配置 `OPENAI_API_KEY`
2. 工具执行可能会根据命令不同而有风险，请谨慎使用
3. 敏感信息不会写入长期记忆
4. 模型调用可能产生费用，请注意使用量

## License

Apache