JSPM

@vtxf/quick-ai

1.0.1
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 14
  • Score
    100M100P100Q41845F
  • License MIT

一个基于命令行的AI助手，支持多种AI模型交互

Package Exports

  • @vtxf/quick-ai
  • @vtxf/quick-ai/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@vtxf/quick-ai) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

quick-ai

概述

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

使用指南

  1. 安装
npm -g i quick-note
  1. 使用
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格式，可以包含详细的指令和示例
  • 修改系统提示词后，新的对话会立即使用更新后的提示词内容