1. 项目概述为什么我们需要一个统一的AI编程接口如果你和我一样是个重度依赖AI辅助编程的开发者那你一定经历过这种“甜蜜的烦恼”手头有好几个不同厂商的AI编程工具比如OpenAI的Codex、Anthropic的Claude Code甚至可能还有DeepSeek、Gemini等等。每个工具都有自己的API密钥、调用方式、参数格式和计费规则。今天想用Claude来重构一段代码明天想用Codex来快速生成一个函数后天又需要DeepSeek来帮忙写注释。每次切换你都得在终端里敲不同的命令或者在不同的IDE插件里切换配置不仅效率低下还容易搞混密钥甚至因为参数格式不对而浪费API调用次数。更让人头疼的是这些工具的CLI命令行界面体验参差不齐。有的安装复杂有的文档不全有的对网络环境有特殊要求。我见过不少开发者明明手握多个强大的AI编程“钥匙”却因为工具链的割裂无法真正实现“编程自由”——那种随心所欲、指哪打哪的流畅感。这个项目的核心就是用LiteLLM这个开源库打造一个统一的、本地的AI编程CLI工具。它的目标很简单让你用一个命令就能调用背后任意一个你拥有的AI模型Codex, Claude Code, DeepSeek等无需关心底层API的差异。你只需要把各个平台的API密钥配置好剩下的就交给这个统一的命令行工具。无论是生成代码、解释代码、重构代码还是调试代码都只需要一套语法极大提升了开发效率和工具使用的幸福感。2. 核心思路与工具选型为什么是LiteLLM在决定自己造轮子之前我调研过几种方案。最简单粗暴的是为每个AI服务写一个独立的Shell脚本或Python脚本。但这意味着我要维护多套逻辑处理多种错误格式毫无扩展性。另一种方案是寻找现成的统一CLI但要么功能不全要么配置复杂要么不再维护。最终我锁定了LiteLLM。它不是一个现成的CLI工具而是一个Python库它的设计哲学完美契合了我的需求“一个统一的接口调用任何LLM大语言模型”。LiteLLM的核心价值在于它抽象了不同AI提供商API的差异。你不需要记住OpenAI的API端点叫/v1/chat/completions而Anthropic的叫/v1/messages也不需要纠结Claude的消息格式是user/assistant而GPT的是system/user/assistant。对LiteLLM来说你只需要告诉它“用claude-3-opus-20240229模型发送这条消息”它就会帮你处理好所有底层的HTTP请求、认证头、参数映射和错误处理。选择LiteLLM作为底层引擎有以下几个决定性优势极简的抽象它提供了completion和chat.completion两个核心函数几乎覆盖所有使用场景。模型名就是“提供商/模型”的格式如openai/gpt-4、anthropic/claude-3-sonnet-20240229直观易懂。强大的提供商支持除了OpenAI和Anthropic它还原生支持Azure OpenAI、Cohere、Replicate、Hugging Face等上百个模型端点。这意味着我们的CLI工具未来可以轻松扩展而无需改动核心调用逻辑。完善的代理与重试机制这对于在国内访问某些服务特别有用。LiteLLM内置了请求重试、回退fallback策略我们可以很方便地为其配置网络代理提高连接稳定性。活跃的社区与清晰的文档这是一个持续维护的项目遇到问题容易找到解决方案或提出Issue。所以我们的项目架构就清晰了以LiteLLM为统一调用引擎在其上封装一个轻量级、易用的Python命令行工具CLI。这个CLI负责读取用户配置API密钥、默认模型等解析命令行参数调用LiteLLM并将结果美观地输出给用户。3. 环境准备与依赖安装工欲善其事必先利其器。我们先来搭建一个干净、可隔离的Python开发环境。我强烈推荐使用conda或venv创建虚拟环境避免污染系统级的Python包。3.1 创建并激活虚拟环境如果你使用condaMiniconda或Anaconda# 创建一个名为ai-code-cliPython版本为3.10的新环境3.9均可 conda create -n ai-code-cli python3.10 -y # 激活环境 conda activate ai-code-cli如果你使用Python内置的venv# 在项目目录下创建虚拟环境 python -m venv venv # 激活环境Linux/macOS source venv/bin/activate # 激活环境Windows PowerShell .\venv\Scripts\Activate.ps1 # 激活环境Windows CMD .\venv\Scripts\activate.bat激活后你的命令行提示符前应该会出现环境名如(ai-code-cli)这表示你正在该虚拟环境中操作。3.2 安装核心依赖我们的项目核心依赖就是litellm。同时为了构建CLI我们会用到typer来简化命令行参数解析用rich来美化控制台输出用python-dotenv来管理环境变量中的密钥。一次性安装所有依赖pip install litellm typer rich python-dotenv这里简单解释一下这几个库litellm: 核心AI调用引擎。typer: 一个基于Python类型提示构建CLI的库比argparse更简洁直观能自动生成--help文档。rich: 让终端输出拥有颜色、样式、表格、进度条等提升用户体验。python-dotenv: 从.env文件加载环境变量安全地管理敏感信息如API密钥。注意litellm的版本迭代较快建议在项目稳定后锁定版本如pip install litellm1.x.x以避免未来API变更导致工具不可用。开发初期可以使用最新版。3.3 获取并配置API密钥这是打通所有AI服务的关键一步。你需要前往各AI服务商的平台创建账户并获取API密钥。OpenAI (Codex/GPT系列):访问 platform.openai.com 。登录后点击右上角个人头像 - “View API keys”。点击“Create new secret key”复制保存。注意密钥只显示一次。Anthropic (Claude系列):访问 console.anthropic.com 。登录后在左侧菜单找到“API Keys”。点击“Create Key”复制保存。其他模型如DeepSeek:根据其官方文档在对应平台创建应用并获取API密钥。安全第一如何管理密钥绝对不要将密钥硬编码在脚本里或上传到GitHub我们使用.env文件来管理。在项目根目录下创建一个名为.env的文件注意开头有个点并填入你的密钥# .env 文件示例 OPENAI_API_KEYsk-your-openai-key-here ANTHROPIC_API_KEYsk-ant-your-anthropic-key-here # 未来可以添加更多 # DEEPSEEK_API_KEYyour-deepseek-key然后在你的Python代码或CLI工具初始化部分通过python-dotenv加载这些变量。系统会自动将其注入到环境变量中litellm能够自动识别OPENAI_API_KEY和ANTHROPIC_API_KEY这些标准的环境变量名。实操心得.env文件务必添加到.gitignore中防止意外提交。你可以提供一个.env.example文件列出需要的环境变量名但不包含真实密钥供其他协作者参考。4. 核心CLI工具设计与实现有了底层引擎和密钥我们现在来设计这个CLI工具。我希望它的命令既简单又强大。基本的使用模式设想为# 基本调用使用默认模型进行对话 aicode “帮我写一个Python函数计算斐波那契数列” # 指定模型调用 aicode --model anthropic/claude-3-haiku-20240307 “优化这段代码的复杂度” # 传入代码文件进行处理 aicode --file ./buggy_script.py “找出这段代码中的潜在错误” # 交互式聊天模式 aicode --chat我们将使用typer来构建这个CLI。首先创建主脚本文件比如叫做aicli.py。4.1 初始化Typer应用与全局配置# aicli.py import typer from rich.console import Console from rich.markdown import Markdown from rich.syntax import Syntax import os from dotenv import load_dotenv import litellm from litellm import completion from typing import Optional, List import tempfile import subprocess # 加载.env文件中的环境变量 load_dotenv() # 初始化Rich控制台用于美化输出 console Console() # 创建Typer应用 app typer.Typer(help 一个统一的AI编程助手CLI通过LiteLLM驱动。) # 全局配置默认模型 # 你可以根据喜好设置比如我更倾向于用Claude Haiku作为默认因为性价比高 DEFAULT_MODEL “anthropic/claude-3-haiku-20240307” # 配置litellm的一些全局设置比如开启详细日志调试用 litellm.set_verbose False # 设为True可以看到详细的请求和响应日志4.2 实现核心ask命令ask命令是核心它接受一个查询字符串调用指定的AI模型并输出结果。app.command() def ask( query: str typer.Argument(..., help“向AI提出的问题或指令。”), model: str typer.Option(DEFAULT_MODEL, “--model”, “-m”, help“指定使用的模型格式如 ‘openai/gpt-4‘ 或 ‘anthropic/claude-3-sonnet‘。”), temperature: float typer.Option(0.2, “--temp”, “-t”, help“生成文本的随机性温度0.0更确定1.0更随机。”), max_tokens: int typer.Option(2000, “--max-tokens”, help“生成回复的最大token数。”), stream: bool typer.Option(False, “--stream”, “-s”, help“是否启用流式输出适合生成长文本。”), ): “”” 向指定的AI模型提问并获取回答。 “”” console.print(f“[dim]正在使用模型 [bold]{model}[/bold] 处理您的请求...[/dim]”) messages [ {“role”: “user”, “content”: query} ] try: if stream: # 流式输出模式 response completion( modelmodel, messagesmessages, temperaturetemperature, max_tokensmax_tokens, streamTrue ) console.print(“[green]AI回复:[/green]”) full_response “” for chunk in response: delta chunk.choices[0].delta.content if delta: full_response delta console.print(delta, end“”, soft_wrapTrue) console.print() # 换行 # 你可以选择将流式输出的完整结果保存下来 # _handle_response(full_response, query) else: # 非流式输出一次性获取结果 response completion( modelmodel, messagesmessages, temperaturetemperature, max_tokensmax_tokens ) ai_response response.choices[0].message.content _handle_response(ai_response, query) except Exception as e: console.print(f“[bold red]请求出错:[/bold red] {e}”) # 这里可以添加更细致的错误处理比如针对配额不足、网络错误等 if “rate limit” in str(e).lower(): console.print(“[yellow]提示: 可能触发了速率限制请稍后再试或检查配额。[/yellow]”) raise typer.Exit(code1) def _handle_response(response_text: str, original_query: str): “”” 统一处理AI的响应文本尝试识别代码块并高亮显示。 “”” # 简单判断如果响应中包含Markdown代码块()或者看起来像代码用语法高亮 if “” in response_text or any(keyword in original_query.lower() for keyword in [“代码”, “program”, “function”, “写一个”]): # 尝试提取代码块并高亮 # 这里是一个简化处理更复杂的可以用正则表达式解析Markdown console.print(Markdown(response_text)) else: # 普通文本用漂亮的排版输出 console.print(f“[bold green]回答:[/bold green]\n”) console.print(response_text) # 提供一个快速复制到剪贴板的选项可选功能需要pyperclip库 # try: # import pyperclip # pyperclip.copy(response_text) # console.print(“[dim]✓ 回答已复制到剪贴板。[/dim]”) # except ImportError: # pass这个ask函数已经具备了核心功能支持流式与非流式输出能处理基本的错误并尝试对代码响应进行美观的Markdown渲染。4.3 实现chat交互模式交互式聊天模式对于复杂的、多轮对话的编程任务非常有用。我们可以实现一个简单的REPL读取-求值-打印循环。app.command() def chat( model: str typer.Option(DEFAULT_MODEL, “--model”, “-m”, help“指定使用的模型。”), system_prompt: str typer.Option(“你是一个资深的软件工程师助手擅长编写清晰、高效、可维护的代码。”, “--system”, “-s”, help“系统提示词设定AI的角色。”), ): “”” 启动一个交互式聊天会话。 “”” console.print(f“[bold blue]进入交互式聊天模式 (模型: {model})[/bold blue]”) console.print(f“[dim]系统指令: {system_prompt}[/dim]”) console.print(“输入 ‘/quit‘ 或 ‘/q‘ 退出 ‘/clear‘ 清空对话历史。\n”) messages [ {“role”: “system”, “content”: system_prompt} ] while True: try: user_input console.input(“[bold cyan]You:[/bold cyan] “) except (EOFError, KeyboardInterrupt): # 处理CtrlD, CtrlC console.print(“\n[yellow]会话结束。[/yellow]”) break if user_input.lower() in (“/quit”, “/q”, “exit”): break if user_input.lower() “/clear”: messages [{“role”: “system”, “content”: system_prompt}] console.print(“[dim]对话历史已清空。[/dim]\n”) continue messages.append({“role”: “user”, “content”: user_input}) console.print(“[dim]AI正在思考...[/dim]”) try: response completion( modelmodel, messagesmessages, streamTrue # 聊天模式推荐用流式体验更好 ) ai_response “” console.print(“[green]AI:[/green] “, end“”) for chunk in response: delta chunk.choices[0].delta.content if delta: ai_response delta console.print(delta, end“”, soft_wrapTrue) console.print() # 换行 messages.append({“role”: “assistant”, “content”: ai_response}) except Exception as e: console.print(f”[bold red]错误:[/bold red] {e}“) # 出错时移除最后一条用户消息避免历史混乱 messages.pop()4.4 实现file命令处理代码文件直接让AI分析或修改本地代码文件是一个高频场景。我们需要读取文件内容并将其作为上下文的一部分发送给AI。app.command() def file( file_path: str typer.Argument(..., help“要分析的代码文件路径。”), instruction: str typer.Argument(..., help“对文件的操作指令如‘解释这段代码’、‘找出bug’、‘重构它’。”), model: str typer.Option(DEFAULT_MODEL, “--model”, “-m”, help“指定使用的模型。”), ): “”” 读取一个代码文件并结合指令发送给AI进行分析。 “”” if not os.path.exists(file_path): console.print(f”[bold red]错误: 文件 ‘{file_path}‘ 不存在。[/bold red]”) raise typer.Exit(code1) try: with open(file_path, ‘r’, encoding‘utf-8’) as f: file_content f.read() except Exception as e: console.print(f”[bold red]读取文件失败:[/bold red] {e}“) raise typer.Exit(code1) # 获取文件扩展名用于语法高亮提示 _, ext os.path.splitext(file_path) language ext[1:] if ext else “text” # 去掉点号 # 构建一个包含文件内容的提示词 prompt f””” 请分析以下{language}代码文件。 文件路径{file_path} 文件内容 {language} {file_content}我的要求是{instruction}请给出你的分析、修改建议或直接输出修改后的代码。 “””console.print(f”[dim]正在分析文件 [bold]{file_path}[/bold] ...[/dim]”) # 复用ask的逻辑但直接调用completion以便更好地控制提示词 messages [{“role”: “user”, “content”: prompt}] try: response completion(modelmodel, messagesmessages, streamTrue) console.print(f”[bold green]分析结果 ({model}):[/bold green]\n”) full_response “” for chunk in response: delta chunk.choices[0].delta.content if delta: full_response delta console.print(delta, end“”, soft_wrapTrue) console.print() except Exception as e: console.print(f”[bold red]处理失败:[/bold red] {e}“)### 4.5 设置入口点与配置管理 为了让我们的aicli命令在终端中随处可用我们需要在pyproject.toml或setup.py中定义入口点。这里以现代项目常用的pyproject.toml为例 toml # pyproject.toml [build-system] requires [“setuptools61.0”, “wheel”] build-backend “setuptools.build_meta” [project] name “ai-code-cli” version “0.1.0” authors [{ name “Your Name”, email “youexample.com” }] description “A unified CLI for AI coding assistants powered by LiteLLM.” readme “README.md” requires-python “3.9” dependencies [ “litellm1.0.0”, “typer0.9.0”, “rich13.0”, “python-dotenv1.0”, ] [project.scripts] aicode “aicli:app” # 关键这行将aicli.py中的app对象注册为aicode命令 [tool.setuptools.packages.find] where [“.”] # 在当前目录查找包创建好pyproject.toml后在项目根目录下以“可编辑”模式安装这个包pip install -e .安装成功后你就可以在终端的任何位置使用aicode命令了例如aicode --help会显示所有命令的帮助信息。5. 高级功能与实战技巧基础CLI搭建完成后我们可以添加一些提升效率和体验的高级功能。5.1 模型回退Fallback与负载均衡LiteLLM的一个杀手级功能是fallback。当你的首选模型因配额不足、服务宕机或速率限制而失败时可以自动切换到备选模型。我们可以在全局配置或具体调用中启用它。修改aicli.py中的调用部分# 在ask命令的try块中可以这样使用fallback try: response completion( modelmodel, # 首选模型 messagesmessages, temperaturetemperature, max_tokensmax_tokens, fallbacks[“anthropic/claude-3-haiku-20240307”, “gpt-3.5-turbo”] # 备选模型列表 )更高级的用法是配置litellm的全局fallback字典为不同错误类型指定不同的备选策略。这需要在工具初始化时配置。5.2 成本计算与使用统计用AI编程成本意识很重要。LiteLLM在响应中会返回usage字段包含消耗的token数。我们可以封装一个函数来估算成本并记录日志。# 简单的成本估算函数价格是示例需根据各平台最新价格更新 MODEL_COST_PER_1K_TOKENS { “gpt-4o”: {“input”: 0.005, “output”: 0.015}, “gpt-4-turbo”: {“input”: 0.01, “output”: 0.03}, “gpt-3.5-turbo”: {“input”: 0.0005, “output”: 0.0015}, “claude-3-opus-20240229”: {“input”: 0.015, “output”: 0.075}, “claude-3-sonnet-20240229”: {“input”: 0.003, “output”: 0.015}, “claude-3-haiku-20240307”: {“input”: 0.00025, “output”: 0.00125}, } def calculate_cost(model: str, usage: dict) - float: “”” 根据使用量估算成本美元。 usage: {‘prompt_tokens‘: 10, ‘completion_tokens‘: 20, ‘total_tokens‘: 30} “”” # 简化处理从完整模型名中提取基础名 base_model model.split(“/”)[-1] if “/” in model else model if base_model not in MODEL_COST_PER_1K_TOKENS: return 0.0 cost_dict MODEL_COST_PER_1K_TOKENS[base_model] input_cost (usage.get(‘prompt_tokens‘, 0) / 1000) * cost_dict[“input”] output_cost (usage.get(‘completion_tokens‘, 0) / 1000) * cost_dict[“output”] return input_cost output_cost # 在_handle_response或ask命令中获取response.usage并调用此函数 # cost calculate_cost(model, response.usage) # console.print(f”[dim]本次调用消耗: {response.usage[‘total_tokens‘]} tokens 约 ${cost:.6f}[/dim]”)你可以将每次调用的模型、token数、成本和时间戳记录到一个CSV或SQLite文件中方便后续分析月度开销。5.3 集成到开发工作流VS Code任务与Git Hook真正的“编程自由”意味着AI助手能无缝嵌入到你现有的工作流中。1. 创建VS Code任务在项目根目录的.vscode/tasks.json中可以定义一键调用CLI的任务。{ “version”: “2.0.0”, “tasks”: [ { “label”: “AI: Explain Selected Code”, “type”: “shell”, “command”: “aicode”, “args”: [ “解释这段代码的功能和潜在问题”, “--model”, “anthropic/claude-3-sonnet-20240229” ], “presentation”: { “echo”: false, “reveal”: “always”, “focus”: false, “panel”: “dedicated”, “showReuseMessage”: false, “clear”: true }, “problemMatcher”: [] } ] }你可以结合VS Code的变量如${selectedText}来动态传递选中的代码。不过更直接的方式是使用VS Code的终端选中代码后右键“在终端中运行选中文本”但前面需要加上aicode ask命令。2. 作为Git Commit Hook你可以在pre-commit或prepare-commit-msg钩子中用AI自动生成或优化commit message。 创建一个脚本git-ai-commit-msg#!/bin/bash # .git/hooks/prepare-commit-msg COMMIT_MSG_FILE$1 # 获取暂存区的变更摘要 DIFF_SUMMARY$(git diff --cached --stat) # 调用我们的CLI生成commit message建议 AI_SUGGESTION$(aicode ask “根据以下git变更摘要生成一个简洁专业的commit message\n$DIFF_SUMMARY” --model claude-3-haiku --temp 0.1 --max-tokens 100) # 将建议写入commit消息文件作为注释 echo “# AI生成的建议: $AI_SUGGESTION” “$COMMIT_MSG_FILE”记得给脚本执行权限(chmod x .git/hooks/prepare-commit-msg)。这样每次git commit时都会看到AI给你的建议。6. 常见问题、故障排查与优化心得在实际搭建和使用过程中我踩过不少坑也总结了一些优化技巧。6.1 网络连接与超时问题这是国内开发者最常见的问题。某些API端点可能连接不稳定。解决方案为LiteLLM配置代理LiteLLM支持通过环境变量或代码设置代理。import os os.environ[“HTTP_PROXY”] “http://your-proxy:port” os.environ[“HTTPS_PROXY”] “http://your-proxy:port” # 或者在调用时指定 # response completion(..., api_base“https://your-proxy-mirror.com/v1”)注意请务必使用合法合规的网络服务遵守当地法律法规。这里提及代理仅作为技术可行性的探讨。调整超时设置默认超时可能太短。import litellm litellm.request_timeout 30 # 将全局请求超时设置为30秒使用Azure OpenAI或其他国内可访问的端点如果你有Azure账户可以使用Azure OpenAI服务其稳定性和可访问性通常更好。LiteLLM完美支持Azure OpenAI只需配置api_base、api_key和api_version。6.2 API密钥错误与配额不足错误信息可能模糊需要仔细辨别。Invalid API Key检查密钥是否正确是否复制了多余空格以及环境变量名是否正确OPENAI_API_KEYvsANTHROPIC_API_KEY。Rate limit exceeded或Quota exceeded表示达到调用频率限制或额度用尽。解决方法是启用上文提到的fallback功能自动切换模型。实现简单的限速器在代码层面控制调用频率。检查对应平台的用量仪表板考虑升级套餐。实操心得将不同模型的密钥都配置好并设置一个成本较低的模型如Claude Haiku或GPT-3.5 Turbo作为默认或首要fallback选项可以有效避免因一个服务出问题而中断工作。6.3 模型响应格式不一致不同模型对系统提示词system prompt的遵循程度、输出代码的格式是否总是用Markdown代码块可能不同。解决方案强化你的提示词Prompt Engineering在指令中明确要求格式。例如在file命令的提示词末尾加上“请将修改后的完整代码放在一个Markdown代码块中。”后处理响应编写一个函数专门用于从AI的响应中提取代码块。可以使用正则表达式例如r“(?:\w)?\n([\s\S]*?)”来匹配。使用LiteLLM的response_format参数如果模型支持例如OpenAI的GPT-4 Turbo支持指定response_format{ “type”: “json_object” }来强制JSON输出但对于代码块提示词工程更通用。6.4 流式输出中断或显示异常在终端中使用流式输出时如果网络波动或控制台不支持某些字符可能导致显示错乱。排查技巧关闭流式输出--streamFalse测试是否是网络问题。尝试在更简单的终端环境如系统自带的Terminal或CMD中测试。检查rich库的版本确保是最新版。如果问题持续可以暂时禁用rich的复杂渲染使用普通打印。6.5 提升代码生成质量的技巧要让AI生成更符合你心意的代码除了调整temperature建议代码生成时设置在0.1-0.3之间降低随机性更重要的是提供高质量的上下文。在file命令中提供更多文件可以修改file命令支持传入多个文件或整个目录的上下文让AI对项目结构有更全面的了解。使用“角色扮演”系统提示词在chat命令中可以预设更具体的角色如“你是一个精通Python异步编程和FastAPI框架的专家注重代码性能和类型安全。”迭代式交互不要期望一次生成完美代码。使用chat模式先让AI生成草稿然后提出具体的修改要求如“这里加上错误处理”、“将函数拆分成两个更小的函数”、“添加详细的文档字符串”。6.6 安全与隐私考量密钥安全.env文件必须加入.gitignore。考虑使用系统密钥链如macOS的Keychain或专门的密钥管理服务来存储API密钥但这会稍微增加CLI的复杂度。代码隐私将公司私有代码或未开源项目代码发送到第三方AI服务前请务必确认该服务的隐私政策。一些服务可能会用数据来训练模型。对于高度敏感的项目考虑部署本地开源模型通过LiteLLM连接本地Ollama或vLLM服务或使用明确承诺不训练数据的商用API。输出验证AI生成的代码尤其是涉及文件操作、系统命令、网络请求或数据库访问的必须经过人工仔细审查后才能运行。永远不要盲目执行AI生成的rm -rf或DROP TABLE这类命令。搭建并熟练使用这个基于LiteLLM的统一AI编程CLI后我个人的开发效率有了肉眼可见的提升。它把分散的工具整合成一个随手可用的“瑞士军刀”让我能更专注于问题本身而不是在不同平台的文档和命令行之间切换。从最初的简单问答到现在的复杂代码重构和系统设计讨论这个工具已经成了我开发环境中不可或缺的一部分。