# smart-agent-cli

**Repository Path**: jerris-code-space/smart-agent-cli

## Basic Information

- **Project Name**: smart-agent-cli
- **Description**: 使用原生 Go 实现的智能体命令行工具
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-29
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Smart Agent CLI

使用**原生 Go** 实现的 AI Agent 终端项目，面向 OpenAI 兼容的 Chat Completions API。
集成了工具调用（OpenAI Function Calling）、记忆系统、上下文压缩、Skill 分层、多智能体协作、子智能体与 Plan 模式。

## 特性

- **工具调用（Function Calling）**：基于 OpenAI 原生 function calling 的推理-调用循环。
- **记忆系统**：短期记忆（对话过程）+ 长期记忆（持久化到 JSON 文件，可按需检索 / 遗忘）。
- **上下文压缩**：基于 token 估算，超阈值时自动把旧消息汇总为摘要，控制上下文成本。
- **Skill 分层**：技能按层级组织（L0 核心 / L1 工具 / L2 领域 / L3 专家），按需递归叠加依赖。
- **多智能体协作**：主控 Agent + 专门子智能体（研究 / 编程 / 系统），通过 `delegate` / `delegate_all` 协作。
- **子智能体**：每个子智能体是独立的 ReAct Agent，可被主控委派子任务。
- **Plan 模式**：先由 LLM 生成计划，再逐步执行并跟踪状态，最后综合结论。

## 依赖

- Go 1.26+（本地已安装）
- 一个 OpenAI 兼容的 API（如 OpenAI / DeepSeek / Qwen / OpenRouter 等）

## 安装与运行

```sh
# 编译
go build -o smart-agent ./cmd/agent

# 启动（首次会自动创建 ~/.smartagent/config/config.yml 并写入默认配置项）
./smart-agent
```

首次启动后，编辑配置文件填入 API 信息：

```yml
# ~/.smartagent/config/config.yml
base_url: https://api.deepseek.com/v1   # OpenAI 兼容 base url（以 /v1 结尾）
api_key: sk-xxxx
model: deepseek-chat
```

运行后输入任意内容即作为任务交给 Agent，输入 `/help` 查看命令。

## 配置

配置默认读取 `~/.smartagent/config/config.yml`，程序启动时自动创建该文件并写入默认配置项。
已设置的对应环境变量会**覆盖**配置文件中的同名项。

| 配置项（YAML key） | 默认值 | 说明 |
|------|--------|------|
| `base_url` | `https://api.openai.com/v1` | OpenAI 兼容服务地址 |
| `api_key` | 空 | API 密钥（必填） |
| `model` | `gpt-4o-mini` | 默认模型 |
| `planner_model` | 空 | 可选，专门的规划模型 |
| `max_steps` | `8` | ReAct 循环最大步数 |
| `max_context_tokens` | `12000` | 触发上下文压缩的阈值 |
| `memory_file` | `agent_memory.json` | 长期记忆持久化文件 |
| `skills_dir` | `skills` | Skill 定义目录（`<技能名>/SKILL.md`） |
| `tool_timeout_sec` | `10` | 工具调用超时（秒） |
| `mock` | `false` | 为 `true` 时启用本地 Mock 回答（调试界面显示，不消耗 token） |
| `AGENT_API_KEY`（环境变量覆盖） | - | API 密钥 |
| `AGENT_MOCK`（环境变量覆盖） | - | 设为 `true`/`1` 开启 Mock 模式 |

## 内置工具

- `shell`：执行 shell 命令
- `read_file`：读取文件
- `write_file`：写入文件（参数格式 `<路径>|<内容>`）
- `list_dir`：列出目录

## Skill 分层结构

技能位于 `skill/builtins.go`，按层级定义；也可在 `AGENT_SKILLS_DIR` 目录放置扩展技能。示意：

| 层级 | 技能示例 |
|------|----------|
| L0 核心 | `core_reasoning` |
| L1 工具 | `shell_ops`、`file_ops` |
| L2 领域 | `coding`、`planning`、`memory_recall` |
| L3 专家 | `collaboration` |

`AGENT_SKILLS_DIR`（YAML key `skills_dir`，默认 `skills`）目录用于扩展技能。每个技能一个子目录，目录名即技能名：

```
skills/<技能名>/SKILL.md
```

`SKILL.md` 采用可选 YAML frontmatter（`---` 包裹）声明元数据 `description` / `level` / `tags` / `depends_on`，正文为技能 Prompt。技能名以**目录名**为权威；frontmatter 可提供 `name`，若给出须与目录名一致（不一致会报错提示）；`level` 默认 2（领域级）、`tags` 默认为 `all`。示例：

````markdown
---
name: web_scraper
description: 抓取并解析网页
level: 2
tags: [all, web, shell]
depends_on: [shell_ops]
---
当任务涉及抓取网页时，用 curl 获取 HTML，再用 grep/sed 提取所需信息。
````

只有 `tags` 与 Agent 所持技能标签（主控为 `all`+`collab`）匹配的技能才会被选中并注入到发给大模型的 system 上下文中。启动后技能名会注入到 `/` 输入补全候选，可直接看到可用技能；输入 `/skills` 查看全部已加载技能。

大模型在收到任务后，会先在上下文中看到这份技能**概要清单**（`skill.RenderCatalog` 提供的名称+描述），据此判断应启用哪个技能；需要细节时再用技能检索工具按需取用：

- `skill-list`：列出全部已加载技能的名称、层级与描述概要。
- `skill-read-doc`：读取指定技能的完整 Prompt 指令。
- `skill-load`：把指定技能加载到当前任务并返回其概要。
- `skill-execute`：返回指定技能要遵循的执行指令。

## CLI 命令

```
/mode           切换 普通模式 / Plan 模式
/mock           开关 Mock 模拟回答（调试界面显示，不消耗 token）
/reset          清空会话上下文
/memory         查看长期记忆
/masters        查看可协作的子智能体
/skills         查看已加载的分层技能
/exit, /quit    退出
/help           帮助
```

输入时可用：
- **上下方向键**：切换上一条 / 下一条已提交的输入历史。
- **`/`**：输入以 `/` 开头时在输入框下方提示可用命令与已加载技能名。

## 测试

```sh
go test ./...