quick-ai

概述

quick-ai 是一个基于命令行的 AI 助手。用户可以在命令行中执行命令，与 AI 进行交互。这是一个nodejs项目，非必要不使用外部库。

使用指南

1. 安装

npm -g i quick-note

2. 使用

qa <用户输入>
qa -c <用户输入>

功能介绍

基本命令

• qa <用户输入>：直接在控制台和 AI 进行交互
• qa -c <用户输入>：接上一次对话内容和 AI 进行交互
• qa -e：打开编辑器查看对话内容
• qa -C：打开配置文件
• qa -p：打开系统提示词配置文件
• qa -h：显示帮助信息

跨平台支持

本工具同时支持 Windows、Linux 和 macOS 系统。

配置文件

配置文件位置

配置文件位于 ~/.quick-ai/config.json，其中 ~ 符号在不同操作系统下解析为用户主目录：

• Windows: %USERPROFILE%\.quick-ai\config.json
• Linux/macOS: ~/.quick-ai/config.json

系统提示词配置文件

系统提示词配置文件位于 ~/.quick-ai/system_prompt.md，用于配置AI对话时的系统提示词：

• Windows: %USERPROFILE%\.quick-ai\system_prompt.md
• Linux/macOS: ~/.quick-ai/system_prompt.md

该文件定义了AI助手的行为和角色。如果文件不存在，系统会自动创建默认的系统提示词。

本地大模型配置示例

{
    "env": {
        "QUICKAI_OPENAI_BASE_URL": "http://localhost:1234/v1",
        "QUICKAI_OPENAI_API_KEY": "",
        "QUICKAI_OPENAI_MODEL": "qwen/qwen3-4b-2507",
        "QUICKAI_EDITOR": "code -r <QUICKAI_HISTORY_DIR> <QUICKNOTE_HISTORY_FILE_PATH>"
    }
}

在线大模型配置示例

{
    "env": {
        "QUICKAI_OPENAI_BASE_URL": "https://open.bigmodel.cn/api/paas/v4",
        "QUICKAI_OPENAI_API_KEY": "your_glm_api_key",
        "QUICKAI_OPENAI_MODEL": "glm-4.5-flash",
        "QUICKAI_EDITOR": "code -r <QUICKAI_HISTORY_DIR> <QUICKNOTE_HISTORY_FILE_PATH>"
    }
}

编辑器配置示例

QUICKAI_EDITOR 环境变量支持多种编辑器配置，以下是一些常见配置示例：

"QUICKAI_EDITOR": "notepad <QUICKNOTE_HISTORY_FILE_PATH>"

"QUICKAI_EDITOR": "vim <QUICKNOTE_HISTORY_FILE_PATH>"

"QUICKAI_EDITOR": "code -r <QUICKAI_HISTORY_DIR> <QUICKNOTE_HISTORY_FILE_PATH>"

用户可以根据自己的喜好和系统环境选择合适的编辑器配置。

配置文件处理逻辑

• 如果配置文件不存在，系统会自动生成默认配置文件
• 系统优先读取配置文件中的环境变量
• 如果配置文件中不存在某个环境变量，则尝试读取系统的环境变量
• QUICKAI_OPENAI_API_KEY 可以不设置，因为某些大模型并不需要 API 密钥

环境变量说明

• QUICKAI_OPENAI_BASE_URL：OpenAI API 基础 URL
• QUICKAI_OPENAI_API_KEY：OpenAI API 密钥（可选）
• QUICKAI_OPENAI_MODEL：使用的模型名称

内置变量

• QUICKAI_HISTORY_DIR：历史记录目录，强制指定为 ~/.quick-ai/history 文件夹
• QUICKNOTE_HISTORY_FILE_PATH：历史记录文件路径，格式为 ~/.quick-ai/history/YYYY/YYYYMM/YYYYMMDD.jsonl，动态指定为当天日期。

历史记录管理

历史文件存储结构

对话历史存储在 ~/.quick-ai/history 文件夹中，采用以下结构：

~/.quick-ai/history/
├── YYYY/                  # 年份目录
│   ├── YYYYMM/            # 年月目录
│   │   ├── YYYYMMDD.jsonl # 日期文件，每行一个 JSON 对话记录
├── last.json              # 最近一次对话的 JSON 文件

对话记录格式

每个对话记录为一个 JSON 对象，格式如下：

{
    "id": 1698704000000,
    "date": "20251020",
    "messages": [
        {
            "role": "user",
            "content": "你好"
        },
        {
            "role": "assistant",
            "content": "你好！有什么我可以帮助你的吗？"
        }
    ]
}

字段说明

• id：对话的唯一标识符，使用毫秒级时间戳
• date：对话发生的日期，格式为 YYYYMMDD
• messages：对话内容数组，每个元素包含 role（user/assistant）和 content 字段

存储规则

• last.json：只存储最近一次对话的完整 JSON 对象
• YYYYMMDD.jsonl：每行存储一个对话的 JSON 对象（不包含换行符，确保整个 JSON 在一行）

命令详细说明

qa <用户输入> 命令

执行流程：

1. 检查 last.json 是否存在且有内容
2. 如果存在，将 last.json 的内容追加到其 date 属性指定的日期的 YYYYMMDD.jsonl 文件末尾
3. 追加完成后，删除 last.json 文件（为新的对话做准备）
4. 如果不存在，跳过历史记录处理
5. 开启新的对话
6. 判断是否获取到AI响应
7. 如果获取到AI响应，创建新的last.json并保存对话内容
8. 如果没有获取到AI响应，打印错误信息到控制台，不创建新的last.json文件

flowchart TD
    A[开始执行qa命令] --> B{检查last.json是否存在且有内容}
    B -->|是| C[将last.json内容追加到对应日期的YYYYMMDD.jsonl文件末尾]
    B -->|否| D[跳过历史记录处理]
    C --> E[删除last.json文件]
    D --> F[开启新的对话]
    E --> F
    F --> G{是否获取到AI响应}
    G -->|是| H[创建新的last.json并保存对话内容]
    G -->|否| I[打印错误信息到控制台]
    H --> J[结束]
    I --> J

qa -c <用户输入> 命令

执行流程：

1. 检查 last.json 是否存在
2. 如果存在，读取 last.json 获取最近对话内容
3. 如果不存在，作为新对话开始
4. 如果存在最近对话内容，基于最近对话内容继续与AI交互
5. 判断是否获取到AI响应
6. 如果获取到AI响应，更新 last.json 保存对话内容（注意：此命令不处理历史记录文件，仅更新last.json）
7. 如果没有获取到AI响应，打印错误信息到控制台，不更新 last.json 文件

flowchart TD
    A[开始执行qa -c命令] --> B{检查last.json是否存在}
    B -->|是| C[读取last.json获取最近对话内容]
    B -->|否| D[作为新对话开始]
    C --> E[基于最近对话内容继续与AI交互]
    D --> F{是否获取到AI响应}
    E --> F
    F -->|是| G[创建或者更新last.json保存对话内容]
    F -->|否| H[打印错误信息到控制台]
    G --> I[结束]
    H --> I

qa -e 命令

执行流程：

1. 打开编辑器，查看当天的历史对话文件 YYYYMMDD.jsonl
2. 将当前目录设置为 ~/.quick-ai/history
3. 获取 QUICKAI_EDITOR 环境变量
4. 替换环境变量中的占位符：
   • <QUICKAI_HISTORY_DIR> 替换为 ~/.quick-ai/history
   • <QUICKNOTE_HISTORY_FILE_PATH> 替换为当天的历史文件路径
5. 控制台要提示用户：最近一次对话内容在last.json文件中，并不在当天的历史文件中（只有之前完成的对话才会被保存到历史文件中）
6. 执行编辑器命令

flowchart TD
    A[开始执行qa -e命令] --> B[设置当前目录为~/.quick-ai/history]
    B --> C[获取QUICKAI_EDITOR环境变量]
    C --> D[替换环境变量中的占位符]
    D --> E[提示用户最近一次对话在last.json中]
    E --> F[执行编辑器命令打开当天历史文件]
    F --> G[结束]

qa -C 命令

执行流程：

1. 检查配置文件目录是否存在
2. 如果不存在，创建配置文件目录
3. 检查配置文件是否存在
4. 如果不存在，创建默认配置文件
5. 获取编辑器命令，优先使用系统默认编辑器
6. 清理编辑器命令中的占位符
7. 执行编辑器命令打开配置文件

flowchart TD
    A[开始执行qa -C命令] --> B[检查配置文件目录是否存在]
    B -->|否| C[创建配置文件目录]
    B -->|是| D[检查配置文件是否存在]
    C --> D
    D -->|否| E[创建默认配置文件]
    D -->|是| F[获取编辑器命令]
    E --> F
    F --> G[清理编辑器命令中的占位符]
    G --> H[执行编辑器命令打开配置文件]
    H --> I[结束]

qa -p 命令

执行流程：

1. 检查系统提示词目录是否存在
2. 如果不存在，创建系统提示词目录
3. 检查系统提示词文件是否存在
4. 如果不存在，创建默认系统提示词文件
5. 获取编辑器命令，优先使用系统默认编辑器
6. 清理编辑器命令中的占位符
7. 执行编辑器命令打开系统提示词文件

flowchart TD
    A[开始执行qa -p命令] --> B[检查系统提示词目录是否存在]
    B -->|否| C[创建系统提示词目录]
    B -->|是| D[检查系统提示词文件是否存在]
    C --> D
    D -->|否| E[创建默认系统提示词文件]
    D -->|是| F[获取编辑器命令]
    E --> F
    F --> G[清理编辑器命令中的占位符]
    G --> H[执行编辑器命令打开系统提示词文件]
    H --> I[结束]

qa -h 命令

执行流程：

1. 显示帮助信息，包括所有可用命令的说明和用法
2. 显示配置文件位置和环境变量说明
3. 显示历史记录存储结构说明
4. 显示常见问题解答和错误处理方法

历史记录查看扩展

除了 qa -e 命令外，用户还可以通过以下方式自由查看历史对话：

1. 直接打开 ~/.quick-ai/history 目录下的任意历史文件
2. 使用任何文本编辑器查看 YYYYMMDD.jsonl 文件
3. 使用命令行工具（如 cat、grep 等）搜索和过滤历史记录

错误处理

配置文件错误

• 如果配置文件不存在，自动生成默认配置文件
• 如果配置文件格式不正确，提示用户并使用默认配置

连接错误

• 如果无法连接到 AI 服务，提示用户连接不成功
• 显示具体的错误原因（如网络问题、API 密钥错误等）
• 连接失败时，结束当前对话并保存已进行的交互到历史记录

其他错误

• 如果历史记录目录无法创建，提示用户并退出
• 如果历史记录文件无法写入，提示用户并退出

技术实现注意事项

跨平台兼容性

• 路径分隔符：Windows 使用 \，Linux/macOS 使用 /
• 环境变量：Windows 使用 %VAR% 或 $env:VAR，Linux/macOS 使用 $VAR
• 命令执行：考虑不同操作系统的命令差异

对话 ID 生成

• 使用毫秒级时间戳作为对话 ID
• 在同一毫秒内发生多次对话的可能性极低，因此不考虑冲突处理

API 密钥处理

• 优先从配置文件中读取 API 密钥
• 如果配置文件中不存在，则从系统环境变量中读取
• 如果两者都不存在，某些模型可能不需要 API 密钥，继续执行

性能考虑

• 历史记录文件按日期分割，避免单个文件过大

系统提示词功能

• 每次AI对话时，系统会自动读取 ~/.quick-ai/system_prompt.md 文件中的内容作为系统提示词
• 系统提示词定义了AI助手的角色和行为。
• 用户可以通过 qa -p 命令编辑系统提示词，自定义AI助手的功能和行为
• 如果系统提示词文件不存在，系统会自动创建提示词

注意事项

• last.json 文件在每次对话结束后会创建或更新，而不是被删除！
• 系统提示词文件支持Markdown格式，可以包含详细的指令和示例
• 修改系统提示词后，新的对话会立即使用更新后的提示词内容