# agentCli

**Repository Path**: yuanboyang/agent-cli

## Basic Information

- **Project Name**: agentCli
- **Description**: The agent supports chat, task execution, and tool invocation.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-04
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mini AutoGPT CLI

Mini AutoGPT CLI 是一个轻量级命令行 Agent，支持 DeepSeek API 和本地 OpenAI-compatible 模型。它提供普通对话、AutoGPT 风格工具调用、会话管理、模型切换和工具启用/禁用能力。

项目入口命令为 `agent`。

## 功能概览

- `chat`：直接对话，适合普通问答和简短任务。
- `run`：Agent 循环执行任务，可自动调用工具并输出最终结果。
- `session`：管理多轮会话。
- `model`：查看和切换模型 provider。
- `tools`：查看、启用或禁用本地工具。
- 支持 DeepSeek API 和本地 `llama-server` OpenAI-compatible endpoint。

默认启用工具：

- `list_dir`：列出工作目录内文件。
- `read_file`：读取工作目录内文件。
- `search_text`：搜索文本。

`write_file` 默认不启用，需要手动开启。

## 安装

推荐使用 Python 3.12 和 `uv`：

```bash
uv sync
```

也可以使用 pip 安装为可编辑包：

```bash
pip install -e .
```

安装后应可使用：

```bash
agent
```

## 配置

复制示例配置：

```bash
cp config.example.toml .ai-agent.toml
```

默认 provider 是 `deepseek`。DeepSeek API key 通过环境变量提供：

```bash
export DEEPSEEK_API_KEY="your-api-key"
```

PowerShell：

```powershell
$env:DEEPSEEK_API_KEY="your-api-key"
```

默认 DeepSeek 配置：

```toml
active_provider = "deepseek"

[providers.deepseek]
type = "openai_compatible"
base_url = "https://api.deepseek.com"
chat_path = "/chat/completions"
model = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"
stream = true
temperature = 0.3
max_tokens = 1024
```

## 本地 MiniCPM 模型

本地模型使用 `llama-server` 的 OpenAI-compatible endpoint。例如：

```bash
llama-server -m /root/minicpm5/MiniCPM5-1B-Q8_0.gguf \
  --port 8080 -ngl 0 -c 8192 --jinja -np 1 -t 8 -b 2048 \
  --mlock --mmap --cont-batching
```

切换到本地 MiniCPM provider：

```bash
agent model switch minicpm
```

本地小模型建议：

- `max_steps` 保持默认 `3`，不建议超过 `5`。
- 上下文窗口先使用 `8192`，不要直接启用 `128K`，避免 CPU prefill 成本过高。
- MiniCPM-1B 适合简单对话；复杂结构化工具调用建议使用更大模型或 API 服务。

## 常用命令

```bash
agent
agent chat "你好"
agent chat "Hi! Please introduce yourself in one sentence."
agent run "读取 README.md 并总结"
agent run "列出当前目录下的文件"
agent session list
agent session new "测试会话"
agent session switch <session-id>
agent model list
agent model switch deepseek
agent model switch minicpm
agent config
agent tools list
```

交互式命令：

```text
/help
/session new 测试
/session list
/session switch <id>
/model list
/model switch deepseek
/tools
/run 读取 README.md 并总结
/exit
```

## 工具使用

查看工具状态：

```bash
agent tools
agent tools list
```

启用或禁用工具：

```bash
agent tools enable write_file
agent tools disable write_file
```

示例：

```bash
agent run "列出当前目录下的文件"
agent run "读取 pyproject.toml 文件的内容"
agent run "在 ai_agent 目录中搜索 'DEEPSEEK' 这个关键词"
```

写文件前需要启用 `write_file`：

```bash
agent tools enable write_file
agent run "创建文件 test_agent.txt，内容为 hello agent"
```

工具有路径安全限制：文件访问必须位于当前工作目录内，跨目录访问会被拒绝。

## 测试结论

已验证能力摘要：

| 功能 | DeepSeek API | MiniCPM-1B 本地 |
|------|:-----------:|:--------------:|
| Chat 对话 | 通过 | 通过 |
| `list_dir` | 通过 | 不稳定 |
| `read_file` | 通过 | 不稳定 |
| `search_text` | 通过 | 未测试 |
| `write_file` | 通过 | 未测试 |
| 模型切换 | 通过 | 通过 |
| 工具启用/禁用 | 通过 | 通过 |

DeepSeek API 在 `chat` 和 `run` 模式下均已通过测试。本地 MiniCPM-1B 可以完成简单对话，但在 AutoGPT 风格结构化工具调用中不稳定，可能出现工具选择错误或重复工具调用。

## 项目结构

```text
ai_agent/
  cli.py              # Typer CLI 入口
  app.py              # 应用组装
  config.py           # 配置加载
  models.py           # 模型/provider 相关类型
  repl.py             # 交互式命令
  agent/              # Agent loop、prompt、parser、上下文
  providers/          # OpenAI-compatible provider
  sessions/           # 会话存储
  tools/              # 内置工具与工具注册
tests/                # 单元测试
config.example.toml   # 示例配置
CLI_USAGE.md          # 使用说明草稿
TEST_REPORT.md        # 测试报告
```