GPT命令行工具开发指南：从核心设计到实战实现

1. 项目概述：一个面向开发者的GPT命令行工具

如果你和我一样，日常开发中经常需要和GPT模型打交道，无论是写代码、调试、还是生成文档，那么一个趁手的命令行工具绝对是效率神器。今天要聊的，就是GitHub上一个名为evilpan/gptcli的项目。从名字就能看出来，这是一个GPT的命令行接口（CLI）工具。它不是那种大而全的AI平台，而是聚焦于一个核心场景：让开发者能在终端里，用最直接、最快捷的方式调用GPT的能力。

想象一下，你正在写一个复杂的正则表达式，或者想快速理解一段陌生的API返回的JSON结构，又或者需要为一段代码生成单元测试。这时候，你不需要离开终端、打开浏览器、登录某个网页、再复制粘贴。你只需要在命令行里敲入类似gptcli “帮我写一个匹配邮箱的正则”这样的命令，答案就直接输出在终端里，甚至可以管道传递给其他命令继续处理。这就是gptcli这类工具的核心价值：将AI能力无缝集成到开发者的核心工作流中，消除上下文切换的成本，让AI助手真正成为“终端里的伙伴”。

这个项目在GitHub上开源，意味着你可以完全掌控它，根据自己的需求进行定制，比如更换模型提供商、调整默认参数、甚至集成到自己的自动化脚本里。对于追求效率和自动化，并且不希望自己的查询数据经过第三方复杂中间服务的开发者来说，一个自托管、可配置的命令行工具，远比一个网页聊天界面更有吸引力。接下来，我们就深入拆解一下，要构建这样一个工具，需要考虑哪些核心问题，以及如何让它真正好用。

2. 核心需求与设计思路拆解

2.1 目标用户与核心痛点

gptcli的目标用户非常明确：开发者、运维工程师、技术写作者等重度终端使用者。这类用户的共同特点是：工作环境以命令行终端为核心，追求效率，习惯使用脚本和自动化工具，对数据隐私和流程可控性有较高要求。

他们的核心痛点有几个：

1. 工作流割裂：需要频繁在终端、浏览器、代码编辑器之间切换，打断心流。
2. 交互效率低下：网页界面通常包含大量非必要的UI元素，加载慢，且复制粘贴操作繁琐。
3. 难以自动化集成：网页服务很难与Shell脚本、CI/CD流水线等自动化工具链集成。
4. 历史记录与上下文管理不便：终端本身有强大的历史记录（如history命令），但网页聊天的历史记录是孤立的，难以检索和复用。
5. 数据隐私顾虑：部分敏感代码或日志不希望经过不可控的第三方前端服务。

gptcli的设计思路，正是围绕解决这些痛点展开的。它不是一个聊天机器人，而是一个生产力工具。它的设计哲学应该是“Unix风格”：做好一件事，并能够与其他工具很好地协作。

2.2 核心功能模块设计

基于上述痛点，一个合格的GPT CLI工具至少需要包含以下几个核心模块：

1. 配置管理模块：这是工具的基石。用户需要能够方便地设置API密钥、选择模型（如gpt-4o、gpt-4-turbo、claude-3-opus等）、配置代理、设置默认参数（如温度temperature、最大令牌数max_tokens）。配置应该支持多环境（如开发、测试）、多模型提供商（OpenAI, Anthropic, 本地模型等），并且能够安全地存储（如使用系统密钥链或加密的配置文件）。

2. 交互模式模块：这是工具的脸面。至少应支持两种模式：

   • 单次查询模式：gptcli “你的问题”。这是最常用的模式，用于快速获得一次性答案。
   • 交互式聊天模式：gptcli -i或直接gptcli进入一个持续的对话会话。在此模式下，需要维护对话历史上下文，支持多轮问答。一个进阶功能是支持“主题会话”，允许用户创建、切换、保存不同的对话线程。

3. 输入输出处理模块：这是工具的桥梁。输入不仅要支持直接字符串，还要能灵活地从文件、管道（stdin）读取内容。例如：

   # 从文件读取 gptcli -f error.log “分析这段日志中的错误” # 从管道读取 cat config.yaml | gptcli “将这份YAML转换成JSON格式”

   输出同样需要灵活：默认输出到终端（stdout），但也要支持重定向到文件，或者以纯文本、JSON等结构化格式输出，方便后续处理。

4. 上下文与历史管理模块：这是工具的记忆。在交互式模式下，需要维护一个会话历史列表。更高级的实现可以支持：

   • 指定上下文窗口大小（例如，只保留最近10条消息作为上下文）。
   • 手动从历史中加载特定会话。
   • 将会话历史导出为Markdown或JSON文件。
   • 本地向量化存储历史记录，实现基于语义的搜索和回顾。

5. 扩展与集成模块：这是工具的翅膀。通过插件机制或简单的脚本包装，可以让gptcli与现有工具链深度集成。例如：

   • 编辑器集成：在Vim/Neovim或VSCode中通过命令调用。
   • Shell别名/函数：创建诸如fix-grammar、explain-code这样的快捷命令。
   • API Server模式：将CLI工具包装成一个简单的HTTP服务，供其他本地应用调用。

注意：设计时的一个关键考量是“默认配置的合理性”。工具开箱即用的体验至关重要。例如，默认模型应该选择一个在效果、速度和成本之间取得平衡的模型（如gpt-4o）；默认的温度参数不宜过高，以保证代码生成等任务的确定性；输出格式应该对终端阅读友好（如自动换行、语法高亮）。

3. 关键技术点与实现解析

3.1 多模型提供商API的抽象与适配

目前市面上主流的LLM API提供商（如OpenAI, Anthropic, Google Gemini， 以及各类开源模型通过Ollama、LM Studio提供的本地API）的接口规范虽然大同小异，但仍有差异。一个健壮的CLI工具不能硬编码只支持一家。

实现策略：采用适配器模式（Adapter Pattern）。定义一个统一的LLMProvider接口，包含核心方法如create_chat_completion(messages, model, temperature, ...)。然后为每个支持的提供商（OpenAI, Anthropic等）实现一个具体的适配器类。这些适配器负责将统一的内部请求格式，转换为对应提供商API所需的特定格式（包括HTTP头、JSON结构、错误处理等）。

# 伪代码示例 class LLMProvider(ABC): @abstractmethod def chat_completion(self, messages, **kwargs): pass class OpenAIProvider(LLMProvider): def __init__(self, api_key, base_url=None): self.client = OpenAI(api_key=api_key, base_url=base_url) def chat_completion(self, messages, model="gpt-4o", temperature=0.7, **kwargs): response = self.client.chat.completions.create( model=model, messages=messages, temperature=temperature, **kwargs ) return response.choices[0].message.content class AnthropicProvider(LLMProvider): # 类似的适配器实现，处理Anthropic特定的API调用 pass

配置层：在用户配置中，可以设置一个default_provider，并为每个提供商单独配置API密钥、基础URL等。CLI命令可以通过--provider openai或--provider anthropic来指定使用哪个提供商。

实操心得：处理流式输出（streaming）时，各家的实现差异更大。OpenAI的SSE（Server-Sent Events）和Anthropic的流式响应格式不同。适配器需要能处理这两种情况，并在CLI中提供--stream参数，实现打字机效果的输出，这对用户体验提升很大。

3.2 灵活的输入源与上下文构建

CLI工具的强大之处在于能利用Unix管道。输入模块需要能智能判断输入来源。

实现逻辑：

1. 检查是否有管道输入（not sys.stdin.isatty()）。如果有，优先读取stdin的全部内容作为用户输入的一部分。
2. 检查-f或--file参数指定的文件。读取文件内容。
3. 检查命令行中直接提供的查询字符串。
4. 如果都没有，在交互式模式下，则等待用户输入；在单次查询模式下，应报错提示。

更复杂的场景是混合输入。例如，用户可能想以文件内容为背景，再附加一个问题：

gptcli -f draft.md “将以上内容翻译成英文，并保持Markdown格式”

这时，需要构建一个包含“系统消息”、“文件内容”（作为用户消息的一部分）和“后续问题”的完整消息列表，发送给LLM。

消息列表构建示例：

messages = [] # 可选的系统提示词，用于设定AI的角色 if system_prompt: messages.append({"role": "system", "content": system_prompt}) # 构建用户消息 user_content = "" if file_content: user_content += f"```\n{file_content}\n```\n\n" # 将文件内容用代码块包裹 if query_from_stdin: user_content += query_from_stdin if query_from_args: user_content += query_from_args if user_content: messages.append({"role": "user", "content": user_content.strip()})

这种构建方式使得工具非常灵活，可以处理多种复杂的查询场景。

3.3 会话管理与持久化

交互式聊天模式的核心是会话管理。一个会话（Session）本质上是一个消息列表的包装，附带一些元数据（如会话ID、创建时间、使用的模型等）。

实现方案：

• 数据结构：使用一个字典或Pydantic模型来代表会话。{“id”: “uuid”, “model”: “gpt-4”, “messages”: [...], “created_at”: “timestamp”}。
• 存储：将会话列表以JSON格式保存在用户本地目录下（如~/.config/gptcli/sessions.json）。每次进入交互模式，加载或创建新会话。每次交互后，自动追加消息并保存。
• 会话操作：
  • gptcli --list-sessions：列出所有历史会话。
  • gptcli --load-session <session_id>：加载特定会话继续对话。
  • gptcli --new-session：明确创建一个新会话。
  • 在交互模式内，可以支持类似/save、/reset这样的内置命令。

高级技巧——上下文窗口修剪：LLM有令牌数限制。长时间对话后，历史消息可能超出限制。需要实现一个“智能修剪”策略。简单的策略是丢弃最早的用户/助理对话对。更复杂的策略可以尝试使用LLM本身来总结之前的对话历史，将总结作为一条系统消息，从而在保留核心信息的同时大幅节省令牌。

3.4 输出格式化与后处理

原始LLM返回的是纯文本。但为了更好的可读性和可用性，输出模块需要做后处理。

1. Markdown渲染：如果终端支持（如通过rich、glow库或配置less），可以将返回的Markdown格式文本渲染成带格式的样式（粗体、斜体、代码块、列表等）。如果不支持，则至少要对代码块进行简单的缩进和语法高亮（使用pygments库）。

2. 结构化输出：对于需要后续脚本处理的场景，提供--json或--raw参数，直接输出API的原始JSON响应或提取出的纯文本内容。

3. 自动复制到剪贴板：对于简短的答案（如一个命令、一个URL），可以添加-c参数，自动将输出结果复制到系统剪贴板，省去鼠标选择的操作。这可以通过pyperclip库实现。

4. 流式输出优化：在流式输出时，除了简单的打印，还可以尝试“单词”或“句子”级别的缓冲输出，让显示更流畅，避免一个字母一个字母地跳动。

4. 实战：从零构建一个简易gptcli核心

理解了设计思路后，我们动手实现一个最核心的、支持OpenAI的单次查询版本。这将帮助我们巩固概念。

4.1 环境准备与依赖安装

首先，创建一个新的Python虚拟环境并安装核心依赖。我们主要需要openai官方库和python-dotenv来管理环境变量。

# 创建项目目录并进入 mkdir my_gptcli && cd my_gptcli # 创建虚拟环境（以venv为例） python3 -m venv venv # 激活虚拟环境 # Linux/macOS source venv/bin/activate # Windows # venv\Scripts\activate # 安装依赖 pip install openai python-dotenv typer rich

• openai: OpenAI官方Python SDK。
• python-dotenv: 从.env文件加载环境变量。
• typer: 一个优秀的库，用于快速构建命令行程序，它基于Python类型提示，能自动生成帮助文档。
• rich: 用于在终端输出漂亮的格式化和语法高亮。

4.2 配置管理与安全

安全地管理API密钥是第一步。我们不应将密钥硬编码在代码中。

1. 创建.env文件：在项目根目录创建.env文件，内容如下：

   OPENAI_API_KEY=sk-your-actual-api-key-here OPENAI_BASE_URL=https://api.openai.com/v1 # 可选，如果你使用代理或自定义端点 DEFAULT_MODEL=gpt-4o

   重要：务必在.gitignore中添加.env，防止密钥被意外提交到版本库。

2. 创建配置加载模块：创建一个config.py文件。

   import os from dotenv import load_dotenv from typing import Optional load_dotenv() # 加载.env文件中的环境变量 class Config: OPENAI_API_KEY: str = os.getenv("OPENAI_API_KEY", "") OPENAI_BASE_URL: Optional[str] = os.getenv("OPENAI_BASE_URL") DEFAULT_MODEL: str = os.getenv("DEFAULT_MODEL", "gpt-4o") @classmethod def validate(cls): if not cls.OPENAI_API_KEY: raise ValueError("OPENAI_API_KEY 未设置。请在.env文件中设置，或通过环境变量导出。")

4.3 核心聊天功能实现

创建core.py，实现与OpenAI API通信的核心函数。

import openai from typing import List, Dict, Any, Optional from config import Config class GPTCore: def __init__(self): Config.validate() self.client = openai.OpenAI( api_key=Config.OPENAI_API_KEY, base_url=Config.OPENAI_BASE_URL ) self.default_model = Config.DEFAULT_MODEL def chat_completion( self, messages: List[Dict[str, str]], model: Optional[str] = None, temperature: float = 0.7, stream: bool = False, **kwargs ) -> Any: """调用OpenAI聊天补全API""" model = model or self.default_model try: response = self.client.chat.completions.create( model=model, messages=messages, temperature=temperature, stream=stream, **kwargs ) return response except openai.APIConnectionError as e: raise Exception(f"连接API失败: {e}") except openai.APIStatusError as e: raise Exception(f"API返回错误状态码: {e.status_code}, {e.response}") except Exception as e: raise Exception(f"未知错误: {e}")

4.4 构建命令行接口

使用typer构建CLI。创建cli.py作为入口点。

import typer from typing import Optional from rich.console import Console from rich.markdown import Markdown from core import GPTCore app = typer.Typer(help="一个简易的GPT命令行工具") console = Console() gpt_core = GPTCore() @app.command() def ask( query: Optional[str] = typer.Argument(None, help="直接输入你的问题"), file: Optional[str] = typer.Option(None, "-f", "--file", help="从文件读取内容作为输入"), model: Optional[str] = typer.Option(None, "-m", "--model", help="指定使用的模型"), temperature: float = typer.Option(0.7, "-t", "--temp", help="生成温度，0-2之间"), stream: bool = typer.Option(False, "-s", "--stream", help="使用流式输出"), ): """ 向GPT提问。问题可以直接输入，或从文件读取，或从管道传入。 """ import sys import os # 1. 构建用户输入内容 user_content_parts = [] # 从文件读取 if file: if not os.path.exists(file): console.print(f"[red]错误: 文件 '{file}' 不存在。[/red]") raise typer.Exit(code=1) with open(file, 'r', encoding='utf-8') as f: file_content = f.read() # 如果是代码或配置文件，可以添加代码块标识 user_content_parts.append(f"```\n{file_content}\n```") # 从标准输入读取（管道） if not sys.stdin.isatty(): # 检测是否有管道输入 stdin_content = sys.stdin.read() if stdin_content.strip(): user_content_parts.append(stdin_content) # 从命令行参数读取 if query: user_content_parts.append(query) # 检查是否有任何输入 if not user_content_parts: console.print("[yellow]提示: 未提供任何输入。请直接输入问题，或使用 -f 指定文件，或通过管道传入内容。[/yellow]") console.print("示例: gptcli '你好，世界！'") console.print("示例: cat log.txt | gptcli '分析错误'") console.print("示例: gptcli -f code.py '解释这段代码'") raise typer.Exit(code=0) user_content = "\n\n".join(user_content_parts).strip() # 2. 构建消息列表 messages = [ {"role": "user", "content": user_content} ] # 3. 调用API try: response = gpt_core.chat_completion( messages=messages, model=model, temperature=temperature, stream=stream ) # 4. 处理输出 if stream: collected_chunks = [] for chunk in response: if chunk.choices[0].delta.content is not None: chunk_content = chunk.choices[0].delta.content console.print(chunk_content, end="", highlight=False) collected_chunks.append(chunk_content) console.print() # 换行 full_reply = "".join(collected_chunks) else: full_reply = response.choices[0].message.content # 使用Rich渲染Markdown输出 md = Markdown(full_reply) console.print(md) except Exception as e: console.print(f"[red]请求失败: {e}[/red]") raise typer.Exit(code=1) if __name__ == "__main__": app()

4.5 安装与使用

最后，我们需要让这个脚本可以作为全局命令使用。在项目根目录创建setup.py或使用pyproject.toml。这里我们用更现代的pyproject.toml。

# pyproject.toml [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "my-gptcli" version = "0.1.0" authors = [{name = "Your Name", email = "you@example.com"}] description = "A simple GPT command-line interface" readme = "README.md" requires-python = ">=3.8" dependencies = [ "openai>=1.0.0", "python-dotenv>=1.0.0", "typer>=0.9.0", "rich>=13.0.0", ] [project.scripts] gptcli = "cli:app"

现在，在开发模式下安装：

pip install -e .

安装成功后，你就可以在终端任何位置使用gptcli命令了。

基础使用示例：

# 直接提问 gptcli "用Python写一个快速排序函数" # 分析文件 gptcli -f server.log "找出日志中所有的错误信息并总结" # 使用管道 echo "apple, banana, cherry" | gptcli "将逗号分隔的列表转换成JSON数组" # 指定模型和温度 gptcli -m gpt-4-turbo -t 0.3 "写一段关于机器学习的严谨定义" # 流式输出（体验打字机效果） gptcli -s "给我讲一个关于程序员的笑话"

至此，一个最核心、可用的GPT CLI工具就完成了。它具备了配置管理、灵活输入、基础输出和流式支持。你可以在此基础上，参考前面章节的设计思路，逐步添加交互式聊天、会话管理、多提供商支持等高级功能。

5. 进阶功能与生态集成思路

一个基础工具只能解决有无问题，要让它真正强大，成为开发者工作流中不可或缺的一环，就需要考虑进阶功能和生态集成。

5.1 插件系统设计

插件可以极大地扩展工具的能力。一个简单的插件系统可以这样设计：

1. 插件接口：定义一个Plugin基类，要求插件实现process_input(user_input)和process_output(llm_output)等方法。插件可以在消息发送给LLM前预处理用户输入，也可以在收到LLM回复后进行后处理。
2. 插件示例：
   • 代码执行插件：当LLM返回一个代码块时，插件可以询问用户是否要执行它（在安全的沙箱环境中）。
   • 网络搜索插件：当用户问题需要实时信息时，插件自动调用搜索API，将结果作为上下文提供给LLM。
   • 文件操作插件：解析类似“将上面生成的代码保存为utils.py”这样的指令，并自动执行文件写入操作。
3. 插件配置：在用户配置文件中，可以启用或禁用特定插件，并配置插件参数。

5.2 与Shell环境的深度集成

真正的效率提升来自于与Shell的无缝融合。

1. Shell函数与别名：在.bashrc或.zshrc中定义快捷函数。

   # 翻译剪贴板内容 alias trans-en="pbpaste | gptcli -t 0.1 '将以下内容翻译成地道英文：'" # 解释上一个命令的错误 alias why-error="gptcli '解释以下shell错误：' \$(tail -5 ~/.bash_history)" # 优化命令 alias optimize-cmd="gptcli '我有一个命令：$1。请提供一个更高效或更安全的写法，并解释原因。'"

2. 命令补全与建议：利用fzf等模糊查找工具，实现历史会话或常用提示词的快速选择。

   # 选择历史会话继续聊天 gptcli --load-session $(gptcli --list-sessions | fzf | cut -d' ' -f1)

3. 作为文本编辑器插件：在Vim/Neovim中，可以映射快捷键，将当前选中的文本或整个缓冲区内容发送给gptcli，并将返回结果插入或替换原有内容。这需要编写编辑器的插件或利用其外部命令调用功能。

5.3 本地知识库与RAG集成

对于需要基于特定文档（如项目文档、内部API手册、个人笔记）进行问答的场景，可以集成检索增强生成（RAG）能力。

1. 本地索引：使用chromadb、faiss等向量数据库，将本地文档切片、嵌入并存储。
2. 检索查询：当用户提问时，首先从本地向量库中检索最相关的文档片段。
3. 增强提示：将检索到的片段作为上下文，与用户问题一起构造提示词发送给LLM。
4. CLI命令扩展：添加gptcli index --dir ./docs命令来索引目录，之后在聊天时，工具会自动进行检索增强。

5.4 性能优化与成本控制

对于高频使用者，性能和成本是需要考虑的实际问题。

1. 缓存：对相同的查询（或查询的嵌入向量相似度很高）进行缓存，直接返回缓存结果，避免重复调用API产生费用和延迟。可以设置缓存的TTL（生存时间）。
2. 令牌使用统计：在每次交互后，输出本次消耗的输入令牌、输出令牌和估算成本。这能帮助用户建立成本意识。
3. 模型路由：实现一个智能路由层。对于简单的代码补全或格式化任务，自动使用更便宜、更快的模型（如gpt-3.5-turbo）；对于复杂的推理和分析任务，再使用gpt-4系列模型。这需要在配置中定义规则。
4. 请求批处理与队列：如果在脚本中需要大量调用，可以实现一个简单的请求队列和批处理机制，但需要注意LLM API通常对并发和速率有限制。

6. 常见问题与排查技巧实录

在实际开发和使用过程中，你肯定会遇到各种问题。下面记录了一些典型问题及其解决方法。

6.1 网络连接与代理问题

这是在国内环境使用国际API服务最常见的问题。

症状：请求超时，或报错包含ConnectionError、Timeout、APIConnectionError等。

排查步骤：

1. 检查基础连接：首先用curl或ping测试是否能访问API域名（如api.openai.com）。如果不能，说明网络层面不通。
2. 配置代理：如果公司或网络环境需要代理，有几种配置方式：
   • 环境变量：在Shell中设置HTTP_PROXY和HTTPS_PROXY环境变量。这是最通用的方法。

     export HTTPS_PROXY=http://your-proxy:port

   • OpenAI客户端配置：新版OpenAI Python库支持在初始化客户端时传入http_client参数，可以传入一个配置了代理的httpx.Client。

     import openai import httpx client = openai.OpenAI( api_key="sk-...", http_client=httpx.Client(proxies="http://your-proxy:port") )

   • 系统代理：确保系统设置中的代理配置正确。
3. 使用镜像或中转服务：如果代理不稳定，可以考虑使用可靠的第三方中转服务，它们通常提供更稳定的连接。这时需要将OPENAI_BASE_URL配置为对应服务的端点。

实操心得：网络问题千奇百怪。一个实用的调试技巧是，在代码中临时启用HTTP请求的详细日志，查看具体的请求和响应头。可以使用httpx的日志级别设置或http.client的调试功能。这能帮你确认请求是否真的发到了正确的地方，以及卡在了哪个环节。

6.2 API密钥与认证失败

症状：返回401 Unauthorized或Incorrect API key provided错误。

排查步骤：

1. 确认密钥格式：OpenAI的密钥以sk-开头。确保复制完整，没有多余的空格或换行。可以在.env文件里检查，或者用echo $OPENAI_API_KEY命令查看环境变量。
2. 检查密钥权限：确认该API密钥是否有权限访问你尝试调用的模型（例如，某些旧密钥可能无法访问最新的gpt-4模型）。
3. 检查密钥余额：登录OpenAI平台，查看该密钥对应的账户是否有余额或额度。
4. 多环境变量冲突：有时系统中可能存在多个同名的环境变量（如Shell session和.env文件都设置了）。确保你的程序读取的是正确的那个。可以在代码中打印出实际使用的密钥前几位进行确认（注意不要打印完整密钥到日志）。

6.3 上下文超长与令牌超限

症状：返回context_length_exceeded错误，或者模型回复突然截断、开始胡言乱语。

排查与解决：

1. 了解模型限制：每个模型都有固定的上下文窗口（如gpt-4o是128K，gpt-4-turbo是128K，gpt-3.5-turbo是16K）。你需要统计输入消息的总令牌数。
2. 实现令牌计数：使用tiktoken库（OpenAI官方）来精确计算消息列表的令牌数。在发送请求前进行检查。

   import tiktoken def num_tokens_from_messages(messages, model="gpt-4o"): encoding = tiktoken.encoding_for_model(model) # 简化计算逻辑 num_tokens = 0 for message in messages: num_tokens += len(encoding.encode(message["content"])) return num_tokens

3. 实现自动修剪：当令牌数接近限制时（例如，达到限制的90%），自动触发修剪策略。最简单的策略是移除最早的一对user和assistant消息。更智能的策略可以尝试总结早期对话。
4. 分块处理长文档：对于超长的文件输入，不要一次性全部塞进去。可以将其分割成多个块，分别发送查询，或者先让模型总结每一块，再基于总结进行问答。

6.4 流式输出中断或乱码

症状：使用--stream参数时，输出到一半停止，或者出现奇怪的字符。

排查步骤：

1. 检查网络稳定性：流式输出对网络稳定性要求更高，任何中断都可能导致连接关闭。确保网络连接可靠。
2. 处理信号中断：在Python代码中，确保捕获了键盘中断（Ctrl+C）等信号，并妥善关闭流式连接。
3. 终端兼容性：某些旧终端或终端模拟器可能对持续刷新的流式输出处理不佳。可以尝试在更现代的终端（如iTerm2, Windows Terminal）中运行。
4. 缓冲区问题：确保标准输出（stdout）没有被缓冲。在Python中，可以设置sys.stdout.reconfigure(line_buffering=True)或在打印时使用flush=True参数。

6.5 回复质量不佳或不符合预期

症状：模型的回复跑题、冗长、格式错误，或者没有遵循指令。

优化策略：

1. 优化系统提示词：系统提示词是引导模型行为最有效的手段。明确、具体地告诉模型你希望它扮演什么角色，输出格式是什么。
   • 差：“你是一个助手。”
   • 好：“你是一个资深的Python开发助手。你的回答应该简洁、准确，专注于提供可执行的代码或明确的建议。如果用户提供代码，请先分析问题，再给出修复方案。代码输出请使用Markdown代码块包裹。”
2. 调整温度参数：对于需要确定性输出的任务（如代码生成、翻译），将温度（temperature）调低（如0.1-0.3）。对于需要创造性的任务（如头脑风暴、写故事），可以调高（如0.7-1.0）。
3. 使用结构化输出：如果可能，要求模型以JSON等特定格式输出。最新的模型（如gpt-4o）支持response_format参数，可以强制其输出JSON，便于后续程序解析。
4. 迭代提示词：不要指望一次就写出完美的提示词。将你的对话历史保存下来，分析哪些提问方式得到了好结果，哪些没有，不断迭代优化你的提问模板。

构建和维护一个像gptcli这样的工具，本身就是一个不断迭代和打磨的过程。从满足最基本的需求开始，逐步添加那些能真正提升你个人或团队效率的功能。最重要的是，它应该完全适配你的工作习惯，成为你思维延伸的自然工具，而不是一个需要你去迁就的软件。