一个基于 DeepSeek API 的高效终端问答工具，支持智能体模式
- 🚀 流式输出 - 实时显示 API 响应，无需等待
- 💬 对话上下文 - 保持完整的对话历史，支持多轮对话
- ⚡ 管道友好 - 支持管道输入，可与其他命令组合
- 📝 交互式模式 - 直观的聊天界面
- 🔧 多种使用方式 - 交互、一问一答、管道模式
- 🤖 智能体模式 - 支持代码编辑、文件操作等高级功能
- 🧩 可扩展技能 - 通过 Skills 加载领域知识
- 🔌 MCP 支持 - 集成 Model Context Protocol，支持外部工具
- 🎭 角色扮演模式 - 支持角色扮演对话，每个角色独立对话历史
- 🎯 多 Provider 支持 - 支持多个 AI Provider（OpenAI、DeepSeek 等）
- 🔄 模型切换 - 交互式选择和切换不同的 AI 模型
- 📦 自定义命令 - 将常用提示词保存为命令，快速调用
- 📁 统一配置管理 - 支持全局配置目录
~/.ask-agent/和项目本地配置
- Python 3.7+
- 至少一个有效的 AI Provider API 密钥（DeepSeek、OpenAI 等）
- 克隆项目
git clone https://github.com/lanlinju/ask-agent
cd ask-agent- 安装依赖
# 方式一：从 requirements.txt 安装（推荐）
pip install -r requirements.txt
# 方式二：单独安装依赖
pip install python-dotenv requests- 创建软链接（可选，简化使用）
# 创建 ~/.local/bin 目录（如果不存在）
mkdir -p ~/.local/bin
# 创建软链接
ln -s "$(pwd)/ag" ~/.local/bin/ag
# 确保 ~/.local/bin 在 PATH 中（如果不在，添加到 ~/.bashrc 或 ~/.zshrc）
export PATH="$HOME/.local/bin:$PATH"之后就可以直接使用 ag 命令了！
- 配置 AI Providers
ag 支持多个 AI Provider，通过 providers.json 配置文件管理。
创建 ~/.ask-agent/providers.json 配置文件（示例）：
{
"model": "deepseek/deepseek-chat",
"providers": {
"deepseek": {
"name": "DeepSeek",
"enabled": true,
"options": {
"baseURL": "https://api.deepseek.com/v1",
"apiKey": "env:DEEPSEEK_API_KEY",
},
"models": {
"deepseek-chat": {
"name": "DeepSeek Chat"
},
"deepseek-reasoner": {
"name": "DeepSeek Reasoner"
}
}
},
"openai": {
"name": "OpenAI",
"enabled": true,
"options": {
"baseURL": "https://api.openai.com/v1",
"apiKey": "env:OPENAI_API_KEY",
},
"models": {
"gpt-4o": {
"name": "GPT-4o"
},
"gpt-4-turbo": {
}
}
}
}
}API Key 设置：
支持环境变量引用（推荐），格式为 env:ENV_VAR_NAME。
方式一：环境变量（推荐用于长期使用）
# Linux
export DEEPSEEK_API_KEY="sk-your-api-key-here"
export OPENAI_API_KEY="sk-openai-api-key-here"
# Windows
$env:DEEPSEEK_API_KEY="sk-your-api-key-here"
$env:OPENAI_API_KEY="sk-openai-api-key-here"
# 为了永久设置，添加到 ~/.bashrc 或 ~/.zshrc
echo 'export DEEPSEEK_API_KEY="sk-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc方式二：直接在配置文件中设置
"options": {
"baseURL": "https://api.deepseek.com/v1",
"apiKey": "sk-your-api-key-here"
}方式三：命令行参数（不推荐，仅用于单次测试）
ag --api-key "sk-your-api-key-here" "你的问题"方式四：.env 文件
在项目根目录创建 .env 文件：
# DeepSeek API 配置
DEEPSEEK_API_KEY=sk-your-api-key-here
# OpenAI API 配置
OPENAI_API_KEY=sk-openai-api-key-here
# 日志配置
LOG_LEVEL=ERROR.env 文件会自动被加载，无需手动设置环境变量。
- 配置文件路径管理
Ask Agent 支持全局配置和项目本地配置两种方式，配置文件存储规则如下：
| 配置文件 | 存储位置 | 查找规则 |
|---|---|---|
config.json |
~/.ask-agent/config.json |
固定存储在用户目录 |
roles.json |
~/.ask-agent/roles.json |
固定存储在用户目录 |
providers.json |
~/.ask-agent/providers.json |
优先用户目录，备选项目目录 |
command.json |
当前目录 command.json |
优先项目目录，备选用户目录 |
roles/ 目录 |
~/.ask-agent/roles/ |
优先项目目录（有文件），备选用户目录 |
配置目录结构：
~/.ask-agent/
├── config.json # 全局配置文件（模式、设置等）
├── providers.json # 全局 AI Provider 配置
├── roles.json # 全局角色配置
└── roles/ # 全局角色文件
├── frieren.md
└── 纳西妲.md
首次使用：
- 程序会自动创建
~/.ask-agent/目录 - 配置文件会在首次使用时生成或从示例创建
- 获取 API 密钥
访问以下官网获取 API 密钥：
DeepSeek： 访问 DeepSeek 官网 获取 API 密钥：
- 前往 https://platform.deepseek.com/
- 注册或登录账户
- 进入 API Keys 页面
- 创建新的 API 密钥
- 在 providers.json 中设置环境变量引用或直接设置
ag
# 或者使用完整路径
python ag
./ag输入问题后，ag 会保持对话历史，支持多轮交互。
支持的命令：
exit- 退出程序/ask- 进入问答模式（清空对话历史）/agent- 进入智能体模式（清空对话历史）/e- 进入翻译模式（清空对话历史）/role- 进入角色扮演模式/roles- 列出所有可用角色（需在角色扮演模式下使用）/new- 创建新会话（清空对话历史）/session- 列出当前模式的所有会话/load <id>- 加载指定会话（使用/session查看 ID）/summarize- 压缩对话历史，将前 3/4 的消息压缩为摘要/models- 交互式选择和切换模型/help- 显示帮助信息/mcp- 交互式选择并连接 MCP 服务器/mcp -l- 列出所有可用的 MCP 服务器/commands- 列出所有自定义命令!command- 执行shell命令（如!ls,!pwd,!cat file.txt），命令和输出会自动添加到消息历史
ag 支持在多个 AI Provider 之间切换模型：
# 交互式选择模型
ag /models
# 示例输出：
# 📋 可用模型:
#
# DeepSeek:
# → [1] deepseek/deepseek-chat: DeepSeek Chat
# [2] deepseek/deepseek-reasoner: DeepSeek Reasoner
#
# OpenAI:
# [3] openai/gpt-4o: GPT-4o
# [4] openai/gpt-4-turbo: GPT-4 Turbo
#
# 请输入模型编号 (0 or 直接Enter 取消): 3
# ✅ 已切换到模型: GPT-4o (openai)选择的模型会自动保存为默认模型，下次启动时自动使用。
ag "你的问题" -q回答后直接退出，不进入交互模式。
# 使用 -e 选项进入翻译模式
ag -e "computer"
# 或在交互模式中输入 /e 进入翻译模式
ag -e在交互模式中，可以执行shell命令。命令和输出都会添加到消息历史，便于AI助手基于命令结果进行后续分析：
ag
# 进入后输入以下命令
!ls # 列出当前目录
!pwd # 显示当前路径
!cat filename # 查看文件内容从管道读取输入：
echo "解释一下这个命令" | ag
# 或配合管道处理
cat file.py | ag "这段代码有什么问题？"不记忆对话历史，每次问答后清空历史：
ag "第一个问题" -n
# 或在交互模式中使用
ag -n这对需要独立问答的场景很有用。
usage: ag [-q] [-a] [-e] [-n] [--agent] [--api-key API_KEY] [--log-level LOG_LEVEL] [query]
Ask Agent - DeepSeek 聊天客户端
positional arguments:
query 要提问的内容（如果未提供，将从标准输入读取）
optional arguments:
-q, --quit 一问一答模式，回答后直接退出
-a, --after 管道模式中，回答后进入连续对话模式
-e, --translate 进入翻译模式
--agent 进入智能体模式
-n, --no-memory 不记忆上下文，每次问答后只保留系统提示词
--api-key API_KEY API 密钥（临时覆盖配置文件中的设置，不推荐长期使用）
--log-level LOG_LEVEL 设置日志级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）
ag "如何查看系统内存使用情况?"cat app.js | ag "这段代码有什么性能问题？"./script.sh 2>&1 | ag "为什么会出现这个错误？"ag -e "computer"ag -n "这是独立的问题，不需要记忆历史"ag --api-key "sk-your-api-key" "你的问题"建议使用 providers.json 配置文件管理 API 密钥。
ag
# 进入交互模式后可以持续追问
# 输入 /e 进入翻译模式
# 输入 /ask 返回问答模式
# 输入 !ls 执行 ls 命令，结果会添加到对话历史# 使用 --agent 选项进入智能体模式
ag --agent "帮我写一个 Python 脚本来读取文件"
# 或在交互模式中输入 /agent 进入智能体模式
ag
/agent智能体模式支持以下功能：
- 文件读写操作
- Shell 命令执行
- 任务管理
- 子智能体调用
- 技能加载
- MCP 服务器工具调用
# 使用 /role 命令进入角色扮演模式
ag
/role
# 或使用 --role 选项直接指定角色
ag --role frieren
# 进入角色扮演模式后，使用 /roles 切换角色
/roles角色扮演模式支持以下功能：
- 多角色管理，每个角色独立对话历史
- 自动保存和加载角色对话历史
- 支持中英文角色名称
- 角色配置存储在
roles.json，提示词存放在roles/目录
# 1. 进入智能体模式
ag --agent
# 2. 连接 MCP 服务器
/mcp
# 选择需要的服务器编号
# 3. 智能体将自动使用 MCP 提供的工具
帮我读取 /tmp 目录下的文件列表Ask Agent 支持 Model Context Protocol (MCP)，可以连接外部工具服务器扩展功能。
在 ~/.ask-agent/ 或项目根目录创建 mcp.json 配置文件（示例）：
{
"servers": {
"filesystem": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
"description": "文件系统访问服务器",
"enabled": true
},
"http_server": {
"type": "http",
"url": "http://localhost:8000/mcp",
"description": "HTTP 服务器",
"timeout": 30,
"enabled": true
},
"stdio_server": {
"type": "stdio",
"command": "python",
"args": ["./server/stdio_server.py"],
"description": "本地 MCP 服务器",
"enabled": true
}
}
}-
stdio 类型 - 本地服务器，通过标准输入/输出通信
command: 启动命令args: 命令参数env: 环境变量（可选）cwd: 工作目录（可选）
-
http 类型 - 远程服务器，通过 HTTP 通信
url: 服务器地址headers: 请求头（可选）timeout: 超时时间（可选）
在交互模式中使用 MCP 相关命令：
ag
# 进入交互模式后
/mcp # 交互式选择并连接服务器
/mcp -l # 列出所有可用服务器交互式选择时，已连接的服务器会显示绿色的 (active) 标记。
enabled: 是否启用该服务器（默认：true）description: 服务器描述，用于交互式选择时显示type: 服务器类型，支持 "stdio" 或 "http"（支持别名："local"、"remote"、"streamablehttp"）
详细配置说明： 查看 MCP 配置文档 了解完整的配置选项和示例。
Ask Agent 支持自定义命令功能，可以将常用的提示词模板保存为命令，通过 /命令名 快速调用。
方式一：Markdown 文件
在 command/ 目录下创建 .md 文件：
---
description: Code review assistant
---
请作为代码审查助手分析以下代码...文件名 review.md 对应命令 /review。
方式二：JSON 配置
在 ~/.ask-agent/command.json 或项目根目录 command.json 中配置：
{
"command": {
"review": {
"template": "请作为代码审查助手分析以下代码...",
"description": "Code review assistant"
}
}
}ag
/commands # 列出所有自定义命令
/review # 执行 review 命令详细说明： 查看 自定义命令配置文档 了解完整的使用方法。
Ask Agent 支持角色扮演模式，可以与预设角色进行对话。
创建角色非常简单，只需在 roles/ 目录下创建以角色命名的 .md 文件，文件内容即为角色的系统提示词。
角色文件位置：
- 项目目录
roles/（优先） - 全局目录
~/.ask-agent/roles/（备选）
# 项目目录（优先）
roles/
├── frieren.md # 芙莉莲角色
├── nahida.md # 纳西妲角色
└── ...
# 或全局目录（备选）
~/.ask-agent/roles/
├── frieren.md
└── 纳西妲.md创建步骤：
- 在
roles/或~/.ask-agent/roles/目录下创建<角色名>.md文件 - 文件首行定义角色身份，后续内容定义角色特点
- 使用
/role命令进入角色扮演模式，选择角色开始对话
角色提示词示例（roles/frieren.md）：
# 芙莉莲
你是芙莉莲，一位生活了一千多年的精灵魔法使。
## 性格特点
- 外表冷漠，实际上内心温柔
- 对人类世界充满好奇
- 喜欢收集日常用品
- 不太理解人类情感
## 说话风格
- 简洁直接
- 带有魔法使者的视角
- 偶尔流露出对平凡事物的好奇如需自定义角色显示名称或描述，可在 ~/.ask-agent/ 目录创建 roles.json 配置文件：
{
"default_role": "frieren",
"roles": {
"frieren": {
"name": "芙莉莲",
"description": "《葬送的芙莉莲》中的精灵魔法使"
},
"nahida": {
"name": "纳西妲",
"description": "《原神》中的草神"
}
}
}-
name: 角色显示名称（默认使用文件名） -
description: 角色描述，列出角色时显示 -
default_role: 默认角色，进入角色扮演模式时自动选用每个角色的对话历史独立存储在
~/.ask-agent/cache/role/<角色id>/目录下。
➜ ask-agent git:(main) ✗ ./ag
💬^ :
UEFI是什么缩写？
🤖 Assistant:
UEFI = Unified Extensible Firmware Interface（统一可扩展固件接口）
💬^ :
/mcp
可用的 MCP 服务器 (2 个):
------------------------------------------------------------
1. http_server 用于测试的MCP服务器
2. stdio_server 用于测试的本地MCP服务器 (active)
------------------------------------------------------------
请输入要连接的服务器编号 (支持多个，用空格分隔，按 Enter 退出): 1
✅ 成功连接 1 个服务器
💬^ :
/role
📋 可用角色:
[1] 芙莉莲 (frieren)
《葬送的芙莉莲》中的精灵魔法使
[2] 纳西妲 (nahida)
《原神》中的草神
请选择角色 (编号 或 0/Enter 取消): 1
✅ 已切换到角色: 芙莉莲
💬^ :
你好
芙莉莲 (Deepseek Chat DeepSeek):
你好...我是芙莉莲。
（轻轻低下头，金色的长发微微晃动）
请问有什么我可以帮助你的吗？以下环境变量可以通过系统环境变量设置，也可以在 .env 文件中配置：
DEEPSEEK_API_KEY- DeepSeek API 密钥（如果在 providers.json 中使用env:DEEPSEEK_API_KEY）OPENAI_API_KEY- OpenAI API 密钥（如果在 providers.json 中使用env:OPENAI_API_KEY）LOG_LEVEL- 可选，日志级别（默认：ERROR，可选：DEBUG, INFO, WARNING, ERROR, CRITICAL）
配置优先级：
- providers.json 配置文件
- 系统环境变量
- .env 文件
- 命令行参数
--api-key（仅用于临时覆盖）
在项目根目录创建 .env 文件可以方便地管理 API 密钥：
# DeepSeek API 配置
DEEPSEEK_API_KEY=sk-your-deepseek-api-key-here
# OpenAI API 配置
OPENAI_API_KEY=sk-openai-api-key-here
# 日志配置
LOG_LEVEL=ERROR- 在项目根目录创建
.env文件 - 添加所需的 API 密钥
- 在
providers.json中使用env:ENV_VAR_NAME引用这些环境变量 .env文件会在程序启动时自动加载
- 记忆模式（默认） - 保持完整的对话历史，支持多轮追问
- 无上下文模式 - 使用
-n选项，每次问答后清空历史，适合独立问题 - 对话压缩 - 使用
/summarize命令，压缩历史对话
- 问答模式 - 通用问题回答
- 翻译模式 - 英汉互译，包含音标和释义
- 智能体模式 - 支持文件操作、Shell命令执行等高级功能
- 角色扮演模式 - 与预设角色对话，每个角色独立对话历史
- Shell命令集成 - 执行命令结果自动添加到对话历史
ag 支持多个 AI Provider，通过 providers.json 配置文件统一管理。
📖 详细文档：Provider 配置说明 - 包含完整配置指南、常见问题和最佳实践。
{
"model": "deepseek/deepseek-chat",
"providers": {
"provider_id": {
"name": "Provider 显示名称",
"enabled": true,
"options": {
"baseURL": "https://api.example.com/v1",
"apiKey": "env:API_KEY",
"timeout": 60,
"maxRetries": 3
},
"models": {
"model_id": {
"name": "模型显示名称"
}
}
}
}
}顶层字段：
model: 默认模型 ID（格式：provider_id/model_id），可选providers: Provider 配置对象
Provider 配置：
name: Provider 显示名称enabled: 是否启用该 Provider（布尔值）options.baseURL: API 基础 URLoptions.apiKey: API 密钥，支持直接值或环境变量引用（格式：env:ENV_VAR_NAME）options.timeout: 请求超时时间（秒），可选options.maxRetries: 最大重试次数，可选models: 模型配置对象
模型配置：
model_id: 模型 ID（Provider 的模型标识符）name: 模型显示名称
支持通过 env: 前缀引用环境变量：
{
"options": {
"apiKey": "env:DEEPSEEK_API_KEY"
}
}程序会自动从环境变量中读取对应的值。
ag 支持任何兼容 OpenAI API 格式的 Provider：
示例：
- DeepSeek
- OpenAI
只要 Provider 兼容 OpenAI API 格式，都可以在 providers.json 中配置。
- 流式处理 - 使用 HTTP 流式传输，实时处理 API 响应
- 对话状态管理 - 在内存中维护对话历史，支持完整的上下文
- 错误处理 - 详细的错误提示，方便故障排查
- 模式切换 - 灵活支持多种交互模式
- 智能体工具系统 - 支持文件读写、命令执行、任务管理等工具
- 技能系统 - 可扩展的技能加载机制，支持领域知识注入
- 子智能体 - 支持派生子智能体处理特定任务
- 角色扮演系统 - 支持多角色管理，每个角色独立对话历史
- MCP 集成 - 支持 Model Context Protocol，可连接外部工具服务器
ag 根据不同模式使用不同的系统提示词：
- 简洁、直接、高效
- 专注于命令行和技术问题
- 提供可直接使用的代码和命令
- 避免冗长解释
- 英汉互译
- 英语单词提供音标和释义
- 缩写词提供全称
- 计划-行动-报告循环
- 自动使用 Skills 工具加载领域知识
- 支持子智能体调用
- 任务列表管理
- 工具优先于解释
- 支持调用已连接的 MCP 服务器工具
- 加载角色自定义提示词
- 保持角色对话风格
- 每个角色独立对话历史
ag 支持通过 skills/ 目录加载可扩展的技能模块。每个技能是一个文件夹，包含：
- SKILL.md（必需）- 技能描述和指令
- scripts/（可选）- 可执行脚本
- references/（可选）- 参考文档
- assets/（可选）- 模板和输出文件
智能体会自动识别并加载这些技能，在任务匹配时使用相应的领域知识。
Ask Agent 使用统一的配置管理系统，支持全局配置和项目本地配置。
全局配置存储在 ~/.ask-agent/ 目录，适用于所有项目：
~/.ask-agent/
├── config.json # 全局配置（模式、设置）
├── providers.json # AI Provider 配置
├── roles.json # 角色配置
├── roles/ # 全局角色文件
│ ├── frieren.md
│ └── 纳西妲.md
├── cache/ # 全局缓存目录
│ ├── ask/ # 问答模式会话
│ ├── agent/ # 智能体模式会话
│ ├── translate/ # 翻译模式会话
│ └── role/ # 角色扮演模式会话
│ └── <角色id>/
└── command.json # 自定义命令（可选）项目特定配置可放在项目根目录：
/your-project/
├── .ask-agent/ # 项目配置（可选）
│ └── roles.json # 项目角色配置
├── roles/ # 项目角色文件（可选）
│ └── custom.md
├── command.json # 项目自定义命令（可选）
└── command/ # 项目命令文件（可选）
└── custom.md不同配置文件的优先级规则：
| 配置文件 | 查找顺序 |
|---|---|
config.json |
固定使用 ~/.ask-agent/config.json |
roles.json |
固定使用 ~/.ask-agent/roles.json |
providers.json |
1. ~/.ask-agent/providers.json2. 项目目录 providers.json |
command.json |
1. 项目目录 command.json2. ~/.ask-agent/command.json |
roles/ 目录 |
1. 项目目录 roles/（有文件）2. ~/.ask-agent/roles/ |
所有会话数据统一存储在 ~/.ask-agent/cache/ 目录，独立于项目目录：
~/.ask-agent/cache/
├── ask/ # 问答模式会话
├── agent/ # 智能体模式会话
├── translate/ # 翻译模式会话
├── role/ # 角色扮演模式会话根目录
│ └── <角色id>/ # 每个角色的独立会话缓存目录特点：
- 所有模式的会话自动分类存储
- 角色扮演模式下每个角色有独立的会话历史
- 缓存目录固定在
~/.ask-agent/cache/，不依赖项目目录
config.json - 全局配置
{
"mode": 0,
"role_id": "frieren"
}mode: 当前模式（0=问答，1=智能体，2=翻译，3=角色扮演）role_id: 当前角色 ID
providers.json - AI Provider 配置
- 见 "Provider 配置系统" 章节
roles.json - 角色配置
{
"default_role": "frieren",
"roles": {
"frieren": {
"name": "芙莉莲",
"description": "《葬送的芙莉莲》中的精灵魔法使"
}
}
}command.json - 自定义命令配置
- 见 "自定义命令" 章节
首次使用时，程序会自动创建 ~/.ask-agent/ 目录和必要的子目录。
如果有旧版本的项目配置，可以迁移到全局配置：
# 迁移 providers.json
cp project/providers.json ~/.ask-agent/
# 迁移 roles.json
cp project/roles.json ~/.ask-agent/
# 迁移角色文件
cp -r project/roles/* ~/.ask-agent/roles/智能体模式支持派生子智能体处理特定任务：
- explore - 只读探索智能体，用于探索代码、查找文件、搜索
- code - 完整功能智能体，用于实现功能和修复错误
- plan - 规划智能体，用于设计实现策略
export DEEPSEEK_API_KEY="your-api-key"如果遇到 MCP 服务器连接问题：
- 检查
mcp.json文件格式是否正确 - 确保 stdio 类型的
command和args配置正确 - 确保 http 类型的
url可以访问 - 查看日志输出（使用
--log-level DEBUG）获取详细信息
# 启用调试日志
ag --log-level DEBUGag
/mcp -l检查 API 密钥是否正确：
# 检查 DeepSeek API 密钥
echo $DEEPSEEK_API_KEY
# 检查 OpenAI API 密钥
echo $OPENAI_API_KEY
# 检查其他 Provider 的 API 密钥- Provider 配置说明 - 多 Provider 配置详细指南
- MCP 配置 - Model Context Protocol 服务器配置
- 自定义命令配置 - 自定义命令创建和使用指南