gcdsfh145
181 lines
4.0 KiB
Markdown
181 lines
4.0 KiB
Markdown
# 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 |