极简终端AI聊天工具gptcli：单文件Python脚本实现OpenAI API兼容客户端

1. 项目概述一个极简的终端AI聊天工具如果你和我一样经常需要在终端里和AI模型对话但又觉得官方网页版太重、第三方客户端功能太杂那么这个项目可能就是你的菜。gptcli是一个用单个Python脚本实现的、功能纯粹的终端聊天客户端。它的核心设计哲学就是“简单”一个文件依赖清晰配置灵活专注于在命令行里完成高质量的AI对话。我最初接触它是因为厌倦了在浏览器标签页之间切换也受够了某些GUI客户端缓慢的启动速度和臃肿的界面。我需要一个能快速启动、随叫随到、并且能完美融入我开发工作流的工具。gptcli完美地解决了这个问题。它本质上是一个对OpenAI API以及任何兼容此API的服务的轻量级封装但它加入了很多贴心的设计比如会话管理、Markdown渲染、流式输出和详细的Token统计让终端聊天体验变得非常顺滑。这个工具特别适合几类人一是开发者可以在不离开终端的情况下快速查询API文档、调试代码片段二是运维或数据分析师需要频繁地用自然语言处理日志或数据三是任何喜欢高效、键盘驱动的极客。它不追求大而全而是把“聊天”这一件事做到极致。接下来我会带你从里到外拆解这个项目分享如何配置、使用以及我在实际使用中积累的一些独家技巧和避坑经验。2. 核心设计思路与架构解析2.1 为什么选择“单文件脚本”架构gptcli最吸引人的特点就是它只有一个主脚本文件gptcli.py。这种设计并非偷懒而是一种深思熟虑的工程选择。对于工具类项目尤其是面向终端用户的CLI工具降低使用门槛是首要任务。单文件意味着部署极其简单用户只需要复制一个文件安装依赖就能运行。无需理解复杂的项目结构。依赖管理清晰所有外部库都明确列在requirements.txt中通过pip一键安装避免了潜在的依赖冲突。易于理解和修改代码逻辑集中用户想要添加自定义功能比如一个新的点命令时可以快速定位相关代码段而不用在多个模块文件中跳转。便于分发和集成你可以直接把这个脚本扔进你的~/bin目录或者作为子模块嵌入到其他项目中都非常轻便。当然单文件脚本的挑战在于如何保持代码的可读性和可维护性。gptcli通过清晰的函数划分和配置分离将配置项抽离到独立的config.json文件很好地平衡了这一点。核心的聊天循环、API调用、流式渲染、命令解析等逻辑被组织在不同的函数中虽然在一个文件里但结构并不混乱。2.2 核心功能模块拆解虽然只有一个文件但我们可以从逻辑上将其划分为几个核心模块配置管理模块负责读取和解析config.json文件并处理环境变量的覆盖逻辑比如优先使用OPENAI_API_KEY环境变量。这是整个程序的起点决定了连接哪个AI服务、使用什么模型等关键行为。API客户端模块基于openai库实际是openai1.0.0的新版客户端封装。这是与AI服务通信的核心。它处理了HTTP请求的构建、代理设置、错误重试以及最重要的——流式stream与非流式响应的处理。会话与上下文管理模块这是智能对话的“记忆”所在。它维护一个历史消息列表并根据配置的context级别0, 1, 2决定在每次请求时携带多少历史记录。这个模块的设计直接影响了对话的连贯性和API调用成本。终端交互与渲染模块负责捕获用户输入、解析点命令如.help,.save、以及将AI返回的Markdown格式内容美观地渲染到终端。它利用了rich或prompt_toolkit这样的库来实现语法高亮、流式文本输出和友好的用户界面。工具命令模块实现了一系列以点开头的内置命令。这些命令扩展了基础聊天功能例如保存/加载会话、切换提示词、查看Token用量等是提升效率的关键。这种模块化思维即使体现在单个文件中也使得每个部分职责清晰为后续的功能扩展和问题排查打下了良好基础。2.3 面向兼容性与灵活性的设计项目描述中强调“Support any OpenAI-Compatible API”这是一个非常重要的特性。它意味着这个工具没有被锁定在OpenAI一家服务上。其实现原理很简单但很有效抽象了API的端点base_url和模型名model。base_url你可以将其指向任何实现了OpenAI Chat Completion API格式的服务。这包括官方OpenAI API (https://api.openai.com/v1)Azure OpenAI Service的端点各类开源模型部署服务如使用vLLM、TGI搭建的服务器第三方代理网关如一些用于访问特定服务的反向代理model你只需要传入该服务支持的模型名称字符串即可。无论是gpt-4o、claude-3-opus如果服务商做了兼容还是qwen-72b-chat工具本身不关心它只是把这个字符串原样传给指定的base_url。这种设计带来了巨大的灵活性。例如在公司内网你可以配置它连接内部部署的Llama或Qwen模型服务器为了获得更快的响应速度你可以连接地理位置上更近的代理节点甚至可以用来测试不同API服务提供商之间的兼容性。我个人的配置里就保存了多个不同base_url和model的配置片段通过.prompt命令或快速编辑配置文件来切换非常方便。注意虽然兼容性好但不同后端对API参数的支援程度可能有细微差别。例如某些开源模型服务可能不支持stream参数或者对max_tokens的处理方式不同。遇到问题时首先需要确认后端服务是否完全兼容OpenAI API规范。3. 从零开始的详细配置与部署指南3.1 环境准备与依赖安装首先你需要一个Python环境。我推荐使用Python 3.8或更高版本。为了避免污染系统环境使用虚拟环境是一个好习惯。# 克隆项目仓库 git clone https://github.com/evilpan/gptcli.git cd gptcli # 创建并激活虚拟环境以venv为例 python3 -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 安装依赖 pip3 install -U -r requirements.txt关键依赖解析openai1.0.0新版OpenAI官方库提供了更规范的客户端接口和异步支持是项目与AI服务通信的基础。rich一个让终端输出变得“富丽堂皇”的库。gptcli用它来渲染Markdown、实现语法高亮和漂亮的流式输出效果。这是提升视觉体验的核心。prompt_toolkit可能被间接依赖一个强大的构建交互式命令行应用的库。它提供了历史记录、自动补全等高级功能使得gptcli的输入体验堪比一个迷你REPL环境。安装过程通常很顺利。如果遇到网络问题可以考虑为pip配置镜像源。安装完成后可以运行pip list确认上述核心库已正确安装。3.2 配置文件深度解析与定制项目提供了一个demo_config.json作为模板。我们的第一步就是复制它并修改为自己的配置。cp demo_config.json conf/config.json现在用你喜欢的编辑器打开conf/config.json。我们来逐一拆解每个配置项的含义和配置技巧{ api_key: sk-xxx, base_url: https://chat.pppan.net/v1, model: gemini-2.5-pro-exp-03-25, context: 2, stream: true, stream_render: true, showtokens: false, proxy: socks5://localhost:1080, prompt: [ { role: system, content: You are a helpful assistant } ], model_choices: [ gemini-2.5-pro-exp-03-25, gemini-2.0-flash, gemini-2.0-flash-lite, gemini-1.5-flash, gemini-1.5-flash-8b, gemini-1.5-pro ] }api_key(推荐通过环境变量设置)这是认证密钥。我强烈建议不要将明文API Key写入配置文件尤其是当你要将配置提交到Git仓库时。更安全的做法是使用环境变量export OPENAI_API_KEYsk-your-actual-key-here程序会优先读取环境变量中的值。这样你的config.json中的api_key字段可以留空或填写一个占位符。base_urlAPI基础地址。默认是OpenAI官方端点。如果你使用其他兼容服务就在这里修改。例如对于Azure OpenAI它的格式通常像https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}。关键点地址末尾的/v1通常是必须的因为OpenAI API的路径前缀就是/v1。model指定默认使用的模型。这个名称必须与你的base_url所指向的服务支持的模型列表相匹配。例如对于OpenAI可以是gpt-4-turbo-preview对于本地部署的Qwen可能是qwen-72b-chat。context这是影响对话体验和成本的核心参数之一。0无上下文。每次提问都是一个全新的独立请求AI没有任何历史记忆。最省Token适合一次性、不相关的问答。1仅将之前的用户提问作为上下文。AI能记住你问过什么但看不到它自己之前的回答。在连贯性需求和Token消耗间取得平衡适合多轮追问但回答不依赖前文细节的场景。2完整的对话上下文用户提问AI回答。AI拥有完整的对话记忆体验最好但Token消耗增长最快因为每次请求都会附上越来越长的历史记录。stream与stream_render流式输出相关。stream: true开启流式响应你会看到答案一个字一个字地“打”出来体验更自然尤其对于长文本。stream_render: true会在流式输出时尝试实时渲染Markdown格式。这很酷但有时在复杂的终端模拟器中可能出现渲染错乱。如果遇到显示问题可以将其设为false流式输出将退化为纯文本。showtokens设为true后每次对话结束会在下方显示本次消耗的Prompt Token、Completion Token和总Token数。对于成本敏感的用户这是必开选项能帮你直观感受不同提问方式和context设置对费用的影响。proxy网络代理设置。支持HTTP/HTTPS/SOCKS。格式必须正确例如http://127.0.0.1:7890或socks5://127.0.0.1:1080。如果你的网络环境需要代理才能访问base_url这里就是配置的地方。prompt系统提示词System Prompt。这是一个强大的定制化工具。你可以在这里定义AI的角色、行为规范、输出格式等。例如你可以将其改为prompt: [ { role: system, content: 你是一位资深Python开发专家回答需简洁、准确代码示例需完整可运行。优先使用标准库。 } ]这会让AI在后续所有对话中都扮演这个角色。model_choices这个列表定义了你在使用.set model name命令时可以切换的模型选项。它只是一个前端便利功能不影响实际的API调用。你可以根据你base_url支持的服务来修改这个列表。3.3 Docker部署方案对于不想污染主机Python环境或者希望获得一致运行环境的用户gptcli也提供了Docker支持。# 1. 构建镜像 docker build -t gptcli:latest . # 2. 运行最简单的方式但需要将API Key放在主机文件里 # 假设你将包含api_key的config.json放在当前目录 docker run -it --rm -v $(pwd)/config.json:/gptcli/config.json gptcli:latest -c /gptcli/config.jsonDocker使用技巧与注意事项配置卷挂载如上例所示-v $(pwd)/config.json:/gptcli/config.json将主机上的配置文件挂载到容器内。这是管理配置的最佳实践无需每次修改都重建镜像。网络模式如果你的config.json中配置了proxy为主机上的代理服务如socks5://localhost:1080在容器内localhost指向的是容器自己而非主机。此时需要让容器使用主机网络docker run -it --rm -v $(pwd)/config.json:/gptcli/config.json --network host gptcli:latest -c /gptcli/config.json使用--network host后容器内的localhost:1080就能访问到主机上运行的代理了。持久化会话如果你使用了.save命令保存会话默认会保存在容器内的/gptcli目录下。为了避免容器退出后会话丢失你可以将这个目录也挂载出来docker run -it --rm -v $(pwd)/config.json:/gptcli/config.json -v $(pwd)/sessions:/gptcli/sessions --network host gptcli:latest -c /gptcli/config.json这样保存的会话文件就会出现在主机的./sessions目录下。4. 核心功能实操与高效使用技巧4.1 启动与基础对话配置完成后在项目根目录下直接运行脚本即可启动交互式聊天界面。./gptcli.py # 或指定配置文件路径 ./gptcli.py -c /path/to/your/config.json启动后你会看到一个简洁的提示符gptcli。直接输入你的问题按回车AI就会开始回答。如果开启了流式输出答案会逐字显示。基础对话示例gptcli 用Python写一个函数计算斐波那契数列的第n项。AI会返回带有语法高亮的代码块。这是最直接的使用方式。4.2 内置点命令详解与高效用法点命令是gptcli的效率倍增器。输入.help可以查看所有命令列表。下面我详细解析几个最常用的.help/.help command查看帮助。使用-v参数可以获得更详细的描述。.multiline处理多行输入的利器。当你需要输入一大段代码、一个复杂的提示词或者一段文本让AI分析时这个命令就派上用场了。输入.multiline后你会进入多行输入模式可以自由换行。输入完成后按CtrlD(Linux/macOS) 或CtrlZ然后回车 (Windows) 提交所有内容。按CtrlC可以取消输入。gptcli .multiline Enter your text (end with CtrlD on empty line, cancel with CtrlC): 请分析以下日志片段找出可能的错误原因 [ERROR] 2023-10-27 14:32:11 Connection timeout to database prod-db [WARN] 2023-10-27 14:32:15 Retrying connection (attempt 1/3) [ERROR] 2023-10-27 14:32:20 Connection timeout to database prod-db [INFO] 2023-10-27 14:32:25 Switching to backup database backup-db 这比在单行里拼接字符串方便太多了。.save/.load会话持久化。.save conversation.md将当前完整的对话历史包括你的提问和AI的回答保存为Markdown文件。这个文件是可读的你可以用任何Markdown编辑器打开、分享或归档。.load conversation.md从之前保存的Markdown或JSON文件中加载对话历史。加载后接下来的对话将基于这个历史继续。这是一个非常重要的功能意味着你可以中断一个复杂的对话改天再加载回来继续。对于调试、写作或者需要多轮迭代的任务来说这是不可或缺的。.reset清空当前会话的历史记录。这相当于开始一个全新的对话但系统提示词prompt会保留。当你想要切换到一个完全不相关的话题时使用这个命令可以避免无关历史消耗Token和干扰AI。.set动态修改参数。.set列出所有可设置的参数及其当前值。.set model gpt-4将当前会话的模型切换到gpt-4。前提是这个模型在你的model_choices列表中并且你的api_key和base_url有权限访问它。.set context 1动态切换上下文模式。例如在进行了一段高成本的完整上下文对话后你可以切换到context 1模式进行一些简单的追问以节省Token。.usageToken用量统计。.usage显示当前会话消耗的Token总数。.usage 7显示过去7天的Token使用详情此功能仅对OpenAI官方API有效因为它需要调用特定的用量查询接口。.usage -d显示详细的计费信息同样仅限OpenAI官方API。这对于监控API开销非常有用。.prompt加载不同的系统提示词。你可以预先准备多个不同角色的提示词文件如prompt_coder.json,prompt_writer.json然后通过.prompt coder快速切换AI的角色。这比每次都去修改config.json要灵活得多。.edit打开文本编辑器。例如.edit config.json可以直接在默认编辑器中打开配置文件进行修改退出编辑器后修改可能不会立即生效取决于实现通常需要重启应用或使用.reload命令如果支持。.quit退出程序。4.3 高级使用场景与技巧结合Shell进行自动化gptcli虽然主要是交互式的但也可以用于简单的脚本。你可以使用管道pipe或 heredoc 向它发送一次性指令。echo 将以下文本翻译成英文你好世界 | ./gptcli.py --no-interactive 2/dev/null | grep -v ^gptcli这需要脚本支持非交互模式--no-interactive或从标准输入读取。如果原脚本不支持可以稍作修改来实现这对于集成到CI/CD或自动化流程中很有用。利用会话文件进行知识沉淀我习惯将每一次有意义的对话都保存下来。例如一个关于“如何用Python优化某个算法”的对话保存为optimize_algorithm.md。几个月后遇到类似问题我不仅可以.load这个文件继续提问还可以直接搜索这个Markdown文件来回顾当时的解决方案。这成了一个私人知识库。分阶段对话策略对于复杂任务我采用“分阶段勤保存”的策略。阶段一头脑风暴与规划。用context 2模式和AI充分讨论生成方案大纲。完成后.save phase1.md。阶段二细节实现。.load phase1.md然后针对大纲的每一部分让AI生成具体代码或文案。过程中可以随时.save phase2.md。阶段三审查与优化。.load phase2.md让AI以审查者的角色检查之前生成的内容提出改进意见。 这样既保持了对话的连贯性又避免了单个会话历史过长导致Token爆炸或AI“遗忘”早期内容。模型切换策略将model_choices配置为你常用的所有模型。在对话中根据需求切换需要深度推理、创意写作时切换到gpt-4或claude-3-opus如果支持。进行简单的代码补全、文本格式化或快速问答时切换到gpt-3.5-turbo或gemini-flash以节省成本和获得更快响应。gptcli让这种切换变得轻而易举。5. 常见问题排查与实战经验分享即使工具设计得再完善在实际使用中也会遇到各种问题。下面是我总结的一些常见问题及其解决方法。5.1 连接与网络问题问题现象可能原因排查步骤与解决方案启动后立即报错APIConnectionError或超时1.api_key错误或未设置。2.base_url不可达网络问题或地址错误。3. 代理配置错误。1.检查API Key运行echo $OPENAI_API_KEY确认环境变量已设置且正确。或在config.json中临时填写Key测试。2.测试网络连通性使用curl -v your_base_url测试端点是否可达。如果使用代理确保代理服务本身是运行的。3.检查代理配置确认proxy字段的协议、IP、端口正确。如果是Docker运行注意localhost的含义可能需要--network host。流式输出卡住或响应极其缓慢1. 网络延迟高或不稳定。2. 服务器端响应慢。3. 流式渲染与终端兼容性问题。1. 尝试关闭stream设为false看是否一次性完整返回。如果可以则是网络或服务器流式响应问题。2. 关闭stream_render让流式输出以纯文本形式显示排除渲染库的兼容性问题。3. 换一个网络环境或时间段测试。错误信息包含403或401认证失败。1. API Key无效或已过期。去对应平台重新生成。2. 对于Azure OpenAI等可能需要检查除了api_key外的其他认证参数如api_version但gptcli的标准配置可能不支持需要修改代码或使用特定的base_url格式。5.2 功能与行为异常问题现象可能原因排查步骤与解决方案AI的回答似乎“忘记”了之前的对话context设置可能为0。输入.set命令检查context的当前值。如果是0将其改为1或2.set context 2。Token用量显示为0或.usage命令不工作1.showtokens未开启。2. 使用的后端API不返回Token用量信息非OpenAI官方API。1. 在config.json中设置showtokens: true或使用.set showtokens true。2. Token统计功能依赖于API响应中的usage字段。许多兼容API如一些开源模型服务可能不返回此字段导致无法统计。这是正常现象。保存的Markdown文件在某些编辑器里渲染不正常AI输出的Markdown可能包含非标准语法或编辑器兼容性问题。gptcli使用rich库渲染它支持的Markdown是CommonMark的一个子集。对于复杂的表格或某些扩展语法渲染可能不完美。可以尝试让AI用更简单的格式输出或者直接在支持rich渲染的终端/工具中查看。输入长文本时被截断可能达到了终端或程序内部的输入长度限制。使用.multiline命令输入长文本这是最可靠的方式。单行输入对长度有限制。5.3 配置与自定义进阶如何添加新的点命令由于是单文件脚本添加新命令相对直接。你需要在脚本中找到解析命令的函数通常叫do_xxx或在一个命令分发字典里。仿照现有的命令如do_save编写你的命令处理函数。将命令名和函数注册到命令列表中。 例如想添加一个.weather命令来查询天气你可以写一个do_weather函数在里面调用一个天气API然后将结果打印出来。这需要对Python和该脚本的代码结构有一定了解。如何修改流式输出的颜色或样式gptcli的渲染依赖于rich库。rich的样式是预定义的。如果你想深度定制需要修改脚本中调用rich.print或rich.markdown的部分传入自定义的style参数。但这属于代码层面的修改了。如何让AI以纯文本模式输出避免Markdown格式最有效的方法是在系统提示词prompt中明确要求。例如在config.json的prompt部分加入“请始终以纯文本格式回复不要使用任何Markdown标记如 #, **, , 等。”5.4 性能与成本优化心得监控Token精明消费始终开启showtokens。你会惊讶地发现一个简单的追问在context 2模式下可能因为携带了很长的历史而消耗数百个Token。对于日常使用context 1通常是性价比最高的选择。只有在进行需要紧密逻辑关联的复杂对话时才切换到context 2。善用.reset和分段保存当一个话题结束立即.reset来清空历史开始新话题。对于长对话每完成一个逻辑段落就.save一次然后.reset开始下一段。最后如果需要整体回顾再用.load合并。这比让一个会话无限增长要经济得多。模型选型策略不要所有任务都用最强大的模型。将model_choices配置好养成根据任务切换模型的习惯。代码补全、文本润色、简单问答用快速廉价模型复杂逻辑推理、创意生成再用大模型。gptcli便捷的.set model命令就是为了这个场景设计的。提示词工程花时间优化你的系统提示词prompt。一个清晰、具体的提示词能极大地减少不必要的来回对话直接生成更符合你期望的结果从而节省总Token数。将调试好的提示词保存为文件用.prompt命令加载。这个工具我已经用了大半年它几乎成了我终端里常驻的伙伴。它的价值不在于功能有多炫酷而在于它完美地嵌入到了我的工作流中安静、高效、可靠。最初我也尝试过其他更复杂的客户端但最终都因为启动慢、配置繁琐或功能过于臃肿而放弃。gptcli的“简单”恰恰是它最强大的地方——它只做好聊天这一件事并且做得足够好。如果你也追求这种极致的效率和简洁不妨试试看或许它也会成为你的生产力利器。