1. 项目概述runprompt一个极简的LLM命令行工具如果你和我一样经常在终端里捣鼓各种LLM模型尝试不同的提示词或者想把AI能力集成到自动化脚本里那你肯定遇到过这样的麻烦每次调用API都得写一堆Python脚本处理参数、解析JSON、管理上下文繁琐得很。更别提在不同项目间复用一套提示词模板了复制粘贴都容易出错。今天要聊的这个工具runprompt就是来解决这些痛点的。它本质上是一个单文件的Python脚本核心功能是让你能在命令行里直接运行.prompt格式的文件把复杂的LLM调用变成一句简单的shell命令。.prompt文件是Google提出的一个开放格式它把提示词模板、模型配置、输入输出结构定义都打包在一个文件里。runprompt这个工具就是.prompt格式的一个轻量级、高可用的命令行实现。你不再需要为每个任务写一个独立的脚本只需要创建一个.prompt文件定义好规则然后像执行普通命令一样使用它。这对于需要反复调试提示词的开发者、希望将AI能力嵌入CI/CD流程的工程师或者只是想快速在命令行里问AI几个问题的用户来说都是一个效率神器。它的设计哲学是“约定优于配置”和“Unix哲学”——每个.prompt文件做好一件事并且能通过管道pipe轻松组合。2. 核心设计思路为什么是单文件脚本与.prompt格式2.1 单文件脚本的哲学与优势runprompt选择以单文件Python脚本的形式分发这背后有非常务实的考量。首先它极大地降低了使用门槛。你不需要一个复杂的Python项目环境不需要处理pip install可能带来的依赖冲突甚至不需要网络如果你已经下载了脚本。只需要一行curl命令就能获得一个功能完整的LLM客户端。这种“开箱即用”的特性对于在服务器、容器环境或者临时调试场景中快速部署AI能力至关重要。其次单文件脚本意味着极致的透明度和可控性。整个工具的代码就在你眼前你可以审计它、修改它或者把它嵌入到你自己的项目里。它不依赖复杂的框架核心逻辑清晰就是读取文件、渲染模板、调用API、返回结果。这种简洁性也带来了稳定性减少了因依赖库版本更新导致的不兼容风险。从工程实践来看这种“自包含”的工具在自动化流水线中更可靠因为它的运行环境是高度可预测的。2.2 .prompt格式将提示词工程“代码化”传统的提示词管理非常松散可能散落在各个Jupyter Notebook、脚本文件甚至聊天记录里。.prompt格式的引入实质上是将提示词工程“代码化”和“模块化”。一个.prompt文件包含两个主要部分YAML格式的Frontmatter前言和Handlebars模板语法的主体。Frontmatter就像这个提示词的“配置文件”或“元数据”。在这里你可以指定使用哪个模型如anthropic/claude-3-5-sonnet、定义输入输出的JSON Schema、设置执行前的Shell命令、声明要使用的工具函数甚至配置缓存行为。这相当于把以往需要通过API参数或环境变量传递的配置都声明式地写在了文件里。模板主体则定义了提示词的具体内容。它支持变量插值、条件判断、循环等逻辑可以从命令行参数、标准输入、或者前置命令的结果中动态获取内容。这种设计使得一个.prompt文件成为一个可复用的、参数化的“函数”。你可以通过传递不同的输入数据让同一个模板完成相似但具体任务不同的工作比如总结不同文章、从不同文本中提取相同结构的信息。这种“文件即函数”的理念使得复杂的AI工作流可以通过组合多个.prompt文件来实现就像在Shell中用管道组合多个简单命令一样自然。这也是runprompt工具设计的核心魅力所在。3. 从零开始安装与第一个.prompt文件3.1 多种安装方式适应不同场景runprompt提供了几种安装方式你可以根据使用习惯和场景选择。最快捷的方式直接下载脚本这是最推荐给新手的入门方式零依赖立即可用。curl -O https://raw.githubusercontent.com/chr15m/runprompt/main/runprompt chmod x runprompt下载后你当前目录下就多了一个名为runprompt的可执行文件。你可以直接使用./runprompt来运行它或者把它移动到系统的PATH目录比如/usr/local/bin/下以便全局调用。使用现代Python包管理器uv如果你已经在使用uv一个快速的Python包和项目管理器那么下面这种方式更优雅它会在一个隔离的环境中运行runprompt不污染你的全局Python环境。uvx --from githttps://github.com/chr15m/runprompt runprompt hello.promptuvx命令会临时安装runprompt并执行它。这对于偶尔使用或不想永久安装的情况非常方便。作为库安装到Python环境如果你计划在更复杂的Python项目中使用runprompt或者希望它像普通命令一样随时可用可以将其安装到你的Python环境中。# 使用uv安装推荐更快更智能 uv pip install githttps://github.com/chr15m/runprompt # 使用pip安装 pip install githttps://github.com/chr15m/runprompt.git安装后你就可以直接在终端任何位置使用runprompt命令了。注意无论哪种方式你都需要准备好对应AI模型的API密钥。例如使用Anthropic的Claude模型就需要设置ANTHROPIC_API_KEY环境变量。这是与AI服务商通信的凭证。3.2 创建并运行你的第一个提示词文件让我们动手创建一个最简单的.prompt文件感受一下它的工作流程。首先用你喜欢的文本编辑器创建一个名为hello.prompt的文件内容如下--- model: anthropic/claude-3-5-sonnet-20241022 --- Say hello to {{name}}!这个文件结构非常清晰---之间的部分是YAML格式的Frontmatter这里只指定了要使用的模型。---之后的部分是提示词模板{{name}}是一个占位符它会被实际传入的数据替换。接下来在运行前设置好API密钥以Anthropic为例export ANTHROPIC_API_KEYsk-your-actual-api-key-here请务必将sk-your-actual-api-key-here替换成你在 Anthropic控制台 获取的真实密钥。现在运行这个提示词文件。有两种方式传递name参数方式一通过命令行参数传递JSON./runprompt hello.prompt {name: World}工具会输出类似Hello, World!的响应。方式二通过标准输入stdin传递JSONecho {name: Alice} | ./runprompt hello.prompt这种方式在构建管道pipeline时特别有用因为前一个命令的输出可以直接作为后一个命令的输入。看到这里你应该已经感受到了runprompt的便捷。它把“编写提示词模板”和“调用AI API”这两个动作解耦了。模板一旦写好就可以像函数一样被反复调用只需改变输入数据。4. 深入功能解析让.prompt文件强大起来4.1 动态内容注入STDIN, ARGS 与 BEFORE一个静态的提示词价值有限runprompt的核心能力在于它能将外部动态内容无缝注入到提示词中。{{STDIN}}与{{ARGS}}这是两个最常用的特殊变量。{{STDIN}}会捕获所有通过管道或重定向传入的标准输入内容并将其作为原始字符串使用。{{ARGS}}则会捕获命令行中在.prompt文件名之后的所有参数并将它们用空格连接成一个字符串。{{INPUT}}的智能选择{{INPUT}}是一个更智能的变量。它的规则是如果提供了STDIN则使用STDIN的内容否则使用ARGS的内容。这让你可以编写既能处理管道输入又能处理命令行参数的通用模板。实战示例创建一个文本总结器假设你经常需要总结长文本可以创建一个summarize.prompt文件--- model: anthropic/claude-3-haiku-20240307 --- 请用中文总结以下文本的核心内容不超过3个要点 {{INPUT}}使用方法非常灵活# 方法1直接粘贴文本作为参数适合短文本 ./runprompt summarize.prompt 这里是一大段需要总结的文本内容... # 方法2总结文件内容 cat long_article.txt | ./runprompt summarize.prompt # 方法3将其他命令的输出作为输入 curl -s https://example.com/news | ./runprompt summarize.promptbefore:指令执行前置命令获取上下文这是runprompt一个非常强大的功能。你可以在发送提示词给AI之前先执行一些Shell命令并将命令的输出作为变量注入到模板中。这为提示词提供了丰富的运行时上下文。例如创建一个code_review.prompt用于代码审查并自动获取当前的Git状态和修改内容--- model: anthropic/claude-3-5-sonnet-20241022 before: git_status: git status --short git_diff: git diff HEAD current_branch: git branch --show-current --- 我当前在 {{current_branch}} 分支上进行开发。 以下是当前的Git状态{{git_status}}以及最近的代码变更{{git_diff}}请基于以上信息对我的代码变更进行审查指出潜在的问题、代码风格不符之处并给出改进建议。运行这个命令时runprompt会先依次执行git status --short、git diff HEAD和git branch --show-current将它们的标准输出分别赋值给git_status、git_diff和current_branch这三个变量然后再渲染模板并发送给AI。这样AI就能获得实时的、准确的代码上下文给出更具针对性的审查意见。实操心得before指令中的命令是在你的默认Shell$SHELL中执行的这意味着你可以使用管道、重定向等所有Shell特性。例如file_count: find . -name *.py | wc -l是完全可以的。但是要小心命令执行失败的情况。如果某个before命令执行失败返回非零状态码其标准错误输出stderr会被捕获并作为该变量的值这可能会导致后续的AI调用出现意外输入。在设计复杂的before命令时最好先单独测试其可靠性。4.2 结构化输出从自由文本到精准JSON很多时候我们调用AI并不是为了得到一段自由的文本回复而是希望获得结构化的数据以便后续的程序化处理。例如从一段简历文本中提取姓名、电话、邮箱从产品描述中提取规格参数或者让AI对一段文本进行情感分类正面/负面/中性。runprompt通过Picoschema一种简化的JSON Schema完美支持了结构化输出。你只需要在Frontmatter的output部分定义你期望的数据结构。实战示例构建一个信息提取器创建一个extract_info.prompt文件--- model: anthropic/claude-3-5-sonnet-20241022 input: schema: text: string output: format: json schema: name?: string, 提取出的中文姓名 phone?: string, 提取出的手机号或电话号码 email?: string, 提取出的电子邮箱地址 education?: array, 提取出的教育经历列表每个元素是字符串 skills: array, 提取出的技能关键词列表 summary: string, 对简历的简短总结 --- 请从以下文本中提取结构化信息 {{text}}注意schema字段的语法字段名: 类型, 描述。字段名后的问号?表示该字段是可选的Optional。支持的基本类型有string、number、integer、boolean、array、object。使用它echo {text: 张三电话13800138000邮箱zhangsanexample.com毕业于北京大学计算机系擅长Python和机器学习。曾在某科技公司担任算法工程师。} | ./runprompt extract_info.prompt你会得到一个干净的JSON输出类似于{ name: 张三, phone: 13800138000, email: zhangsanexample.com, education: [北京大学计算机系], skills: [Python, 机器学习, 算法], summary: 一名具有计算机背景擅长Python和机器学习的算法工程师。 }这个JSON可以直接被jq等工具解析或者作为下一个.prompt文件的输入实现工作流的自动化串联。4.3 工具Tools系统赋予AI行动能力如果AI只能“思考”而不能“行动”那它的能力就被限制在了信息处理层面。runprompt的工具Tools系统允许你在提示词中声明一些Python函数或Shell命令AI模型在推理过程中可以主动调用这些工具来获取信息或执行操作然后将工具返回的结果整合到它的思考中再给出最终回答。这实质上是在构建一个简单的AI智能体Agent。4.3.1 定义Python工具工具就是普通的Python函数但需要有一个清晰的文档字符串docstring这个字符串会被转换成工具的描述供AI理解。创建一个my_tools.py文件import requests import json from datetime import datetime def get_weather(city: str) - dict: 获取指定城市的当前天气信息。 参数: city (str): 城市名称例如“北京”、“Shanghai”。 返回: dict: 包含温度(temp)、天气状况(conditions)、湿度(humidity)等信息的字典。 # 这里是一个模拟实现。实际应用中你应该调用真实的天气API如OpenWeatherMap。 # 记得处理网络错误和API限流。 print(f[工具调用] 正在查询{city}的天气..., filesys.stderr) # 模拟API调用延迟 time.sleep(0.5) # 返回模拟数据 return { temp: 22, conditions: 晴, humidity: 65, city: city } def search_web(query: str, max_results: int 3) - list: 在网络上搜索相关信息模拟。在实际应用中可以集成Serper、Google Search API等。 参数: query (str): 搜索关键词。 max_results (int): 返回的最大结果数量默认为3。 返回: list: 搜索结果列表每个元素是一个包含标题(title)和摘要(snippet)的字典。 print(f[工具调用] 正在搜索: {query}, filesys.stderr) # 模拟搜索 return [ {title: f关于{query}的结果1, snippet: f这是关于{query}的第一个模拟摘要。}, {title: f关于{query}的结果2, snippet: f这是关于{query}的第二个模拟摘要。} ][:max_results] def calculate(expression: str) - float: 安全地计算数学表达式。使用Python的ast.literal_eval进行安全评估仅支持基本算术。 参数: expression (str): 数学表达式如3 5 * 2。 返回: float: 计算结果。 import ast try: # 使用ast.literal_eval进行安全评估避免执行任意代码 node ast.parse(expression, modeeval) # 可以在这里添加更严格的安全检查例如只允许特定的ast节点类型 for subnode in ast.walk(node): if isinstance(subnode, (ast.Call, ast.Attribute)): raise ValueError(表达式包含函数调用或属性访问不安全) return eval(compile(node, filenameast, modeeval)) except (SyntaxError, ValueError) as e: return f计算错误: {e}4.3.2 在提示词中使用工具在.prompt文件的Frontmatter中通过tools字段引入定义好的工具模块。--- model: anthropic/claude-3-5-sonnet-20241022 tools: - my_tools.* # 导入my_tools.py中所有带有文档字符串的函数 --- 用户的问题是{{query}} 请根据需要使用可用的工具来获取必要信息然后回答用户的问题。4.3.3 运行与交互当你运行这个提示词时如果AI认为需要调用工具来回答问题它会发出请求并在终端向你确认./runprompt assistant.prompt {query: 北京今天天气怎么样然后计算一下(15 27) * 3的值。} # 输出过程可能如下 # [工具调用] 正在查询北京的天气... # 工具调用: get_weather # 参数: {city: 北京} # 运行此工具 [y/n]: y # ... (工具返回结果) # [工具调用] 正在计算表达式... # 工具调用: calculate # 参数: {expression: (15 27) * 3} # 运行此工具 [y/n]: y # ... (工具返回结果) # 最终AI会整合工具返回的信息给出综合回答 # “根据查询北京今天天气晴朗气温22摄氏度湿度65%。另外(15 27) * 3 的计算结果是126。”4.3.4 安全工具与自动化批准对于只读、无风险的工具如查询天气、计算数学题你可以将其标记为“安全safe”这样在配合--safe-yes标志运行时这些工具调用将自动被批准无需人工确认从而实现全自动化。def get_weather(city: str) - dict: 获取天气信息只读操作。 # ... 实现 ... return weather_data get_weather.safe True # 标记为安全工具运行命令./runprompt --safe-yes assistant.prompt {query: ...}标记为safe的工具将自动运行而未标记的工具仍会请求确认。这对于构建自动化流水线至关重要。4.3.5 内置工具与Shell工具除了自定义Python工具runprompt还提供了一系列开箱即用的内置工具builtin.*如calculator安全计算器、fetch_clean获取并清理网页内容、datetime获取当前时间等。你甚至可以直接在Frontmatter中定义简单的Shell工具--- model: anthropic/claude-3-5-sonnet-20241022 shell_tools: list_files: ls -la count_lines: wc -l --- 请列出当前目录的文件并统计某个文件的行数。Shell工具让AI能够直接与你的操作系统进行有限的、受控的交互极大地扩展了其应用场景。4.4 文件附件与上下文管理在处理复杂任务时经常需要让AI阅读本地文件的内容比如代码审查、文档分析等。runprompt提供了便捷的文件附件功能。通过Frontmatter附加文件在Frontmatter中使用files字段可以指定要附加的文件或URL。支持通配符glob。--- model: anthropic/claude-3-5-sonnet-20241022 files: - README.md - src/**/*.py # 附加src目录下所有.py文件 - https://example.com/specification.pdf --- 请综合分析附带的README文档和源代码给出项目结构的概述和潜在的改进点。通过命令行附加文件你也可以在运行命令时动态附加文件这在临时分析时非常方便。./runprompt --read report.pdf --read data/*.csv analyze.prompt--read或它的别名--file参数可以多次使用也支持通配符。命令行附加的文件会和Frontmatter中定义的文件合并后一起发送给AI。注意事项附加文件会显著增加API调用的令牌Token数量从而影响成本和速度。对于大型文件AI模型可能有上下文长度限制。在实际使用中最好先对文件进行预处理例如只提取相关章节或者使用before指令动态生成文件的摘要后再附加。5. 高级配置与生产环境实践5.1 分层配置系统为了适应不同场景开发、测试、生产runprompt采用了一个灵活的分层配置系统优先级从低到高依次为配置文件 - 环境变量 - 命令行参数。1. 配置文件配置文件允许你设置默认值避免每次运行都输入重复参数。runprompt会按顺序查找并加载以下位置的配置文件项目级./.runprompt/config.yml当前目录下用户级~/.config/runprompt/config.yml遵循XDG标准用户级备选~/.runprompt/config.yml一个典型的配置文件如下# ~/.config/runprompt/config.yml # 默认模型当prompt文件、环境变量、命令行都未指定时使用 default_model: anthropic/claude-3-haiku-20240307 # 工具搜索路径 tool_path: - ~/my_ai_tools - /team/shared_tools # 启用缓存加速开发调试 cache: true # 对于标记为safe的工具自动批准运行 safe_yes: true # API密钥注意将密钥放在配置文件中需确保文件权限安全 anthropic_api_key: sk-your-anthropic-key-here openai_api_key: sk-your-openai-key-here2. 环境变量环境变量适合在脚本或容器化部署中设置。所有配置都有对应的RUNPROMPT_前缀环境变量。export RUNPROMPT_MODELopenai/gpt-4o export RUNPROMPT_CACHE1 export RUNPROMPT_ANTHROPIC_API_KEYsk-...3. 命令行参数命令行参数的优先级最高用于覆盖配置文件和环境变量的设置。./runprompt --model googleai/gemini-1.5-pro --no-cache my_prompt.prompt5.2 连接本地或自定义模型如Ollamarunprompt不仅支持云服务商Anthropic, OpenAI, Google还通过base_url配置支持任何兼容OpenAI API格式的端点。这使得连接本地部署的模型如Ollama、LM Studio、vLLM等变得非常简单。连接本地Ollama服务假设你在本地运行了Ollama并拉取了llama3.2模型。启动Ollama服务通常默认在http://localhost:11434。配置runprompt使用该端点。# 通过环境变量设置推荐便于脚本化 export RUNPROMPT_BASE_URLhttp://localhost:11434/v1 # 或者通过命令行参数 ./runprompt --base-url http://localhost:11434/v1 --model ollama/llama3.2 hello.prompt注意当设置了base_url后模型名称中的提供商前缀如ollama/会被忽略因为所有请求都发往你指定的端点。但保留前缀有助于提示词文件的可读性。配置提示词文件使用本地模型你可以在.prompt文件中直接指定本地模型结合项目级配置文件让团队所有成员都能一键运行。# .prompt 文件 --- model: ollama/llama3.2 # 名称可自定义主要起标识作用 --- 你的提示词...# ./.runprompt/config.yml (项目级配置) base_url: http://localhost:11434/v1这样任何在该项目目录下运行runprompt的人都会自动使用本地的Ollama服务。5.3 缓存机制提升开发效率与降低成本在调试和迭代提示词时你可能需要反复运行同一个.prompt文件仅修改细微的模板语法。每次调用都访问AI API既慢又贵。runprompt的缓存功能就是为了解决这个问题。启用缓存后工具会计算当前调用的“指纹”基于提示词模板、输入数据、模型配置等如果相同的请求之前执行过它会直接返回缓存的结果而不会再次调用API。启用缓存# 单次启用 ./runprompt --cache analyze.prompt input.json # 或使用短选项 ./runprompt -c analyze.prompt input.json # 通过环境变量全局启用适合开发会话 export RUNPROMPT_CACHE1缓存文件默认存储在~/.cache/runprompt/或$XDG_CACHE_HOME/runprompt/目录下。你可以通过--cache-dir参数或RUNPROMPT_CACHE_DIR环境变量自定义缓存目录。缓存的使用场景与注意事项场景最适合提示词开发、模板调试、以及输入数据固定的自动化任务。清理当你想强制刷新结果时可以手动删除缓存目录或使用--no-cache标志运行。局限性缓存是基于精确匹配的。即使你只修改了模板中的一个空格也会被视为新的请求。对于before指令中动态变化的内容如date命令需要特别注意因为这会导致每次运行的“指纹”都不同缓存失效。5.4 交互式聊天模式虽然.prompt文件擅长处理单次任务但有时你需要与AI进行多轮对话。runprompt提供了--chat模式。基于提示词文件启动聊天你可以从一个定义了角色或上下文的.prompt文件开始聊天。# expert.prompt --- model: anthropic/claude-3-5-sonnet-20241022 chat: true # 在Frontmatter中声明这是聊天模式 --- 你是一位资深的Linux系统架构师擅长性能调优和故障排查。请用专业但易懂的方式回答用户的问题。运行./runprompt --chat expert.prompt。之后你就可以在终端里与这位“架构师”进行多轮对话了。对话历史会保存在内存中直到你退出。裸聊天模式你也可以不指定提示词文件直接指定模型开始聊天./runprompt --chat --model openai/gpt-4o这在快速测试模型或进行自由对话时很方便。退出聊天输入/exit、/quit或按下CtrlD(EOF)。6. 实战工作流构建与问题排查6.1 构建自动化信息处理管道runprompt真正的威力在于将多个简单的.prompt文件通过Unix管道组合成复杂的工作流。每个文件负责一个明确的子任务遵循“单一职责原则”。场景监控服务器日志提取错误信息分析原因并生成报告。提取错误行extract_errors.prompt--- model: anthropic/claude-3-haiku-20240307 --- 请从下面的系统日志中筛选出所有包含“ERROR”或“FATAL”级别的行并按时间顺序排列。 日志 {{STDIN}}分析错误原因analyze_errors.prompt--- model: anthropic/claude-3-5-sonnet-20241022 input: schema: error_logs: string output: format: json schema: primary_cause: string, 最主要的错误原因 affected_components: array, 受影响的系统组件列表 suggested_actions: array, 建议的排查或修复步骤 --- 你是一名SRE工程师。请分析以下错误日志推断根本原因、影响范围并提供初步的解决建议。 错误日志 {{error_logs}}生成报告generate_report.prompt--- model: googleai/gemini-1.5-pro input: schema: analysis: object --- 请根据以下JSON格式的分析结果生成一份给非技术经理的简要事件报告。 报告需包含事件概述、根本原因通俗解释、影响、已采取/建议的行动、后续预防措施。 请使用清晰的标题和项目符号。 分析结果 {{analysis}}组合管道tail -f /var/log/syslog | grep --line-buffered -E ERROR|FATAL | \ ./runprompt extract_errors.prompt | \ ./runprompt analyze_errors.prompt | \ ./runprompt generate_report.prompt incident_report.md这个管道会实时监控日志自动提取、分析错误并生成报告。你可以将其设置为一个定时任务或后台服务。6.2 常见问题与排查技巧在实际使用中你可能会遇到一些问题。以下是一些常见问题的排查思路1. 错误ModuleNotFoundError: No module named anthropic原因你以单文件脚本方式运行runprompt但未安装Anthropic Python SDK却试图调用Anthropic模型。解决方案A推荐安装对应的提供商SDK。runprompt单文件脚本会尝试动态导入。对于Anthropicpip install anthropic。对于OpenAIpip install openai。方案B使用uvx方式运行uv会自动处理依赖。方案C安装完整版runprompt库它会包含常用依赖。2. 错误Invalid API key或Authentication error原因API密钥未设置或设置不正确。排查检查密钥是否正确无误是否有多余空格。确认设置的环境变量名称正确。对于Anthropic可以是ANTHROPIC_API_KEY或RUNPROMPT_ANTHROPIC_API_KEY。运行echo $ANTHROPIC_API_KEY确认环境变量已导出到当前shell会话。如果你在配置文件中设置了密钥请检查配置文件路径和YAML语法是否正确。3. 工具Tools导入失败原因runprompt找不到你定义的Python工具文件。排查确认工具文件如my_tools.py所在目录是否在工具搜索路径中。搜索路径包括当前目录、提示词文件所在目录、通过--tool-path指定的目录、以及默认的./.runprompt/tools等目录。检查工具函数是否有文档字符串docstring。没有docstring的函数不会被识别为工具。使用--verbose-v标志运行查看详细的导入过程和错误信息。4. 响应速度慢或令牌消耗过高原因提示词过长、附加了大型文件、或模型本身较慢。优化精简提示词移除不必要的上下文和指令。预处理附件使用before指令先对大型文件进行摘要例如用head -n 100取前100行或用grep提取关键部分再将摘要而非全文附加。选择合适模型对于简单任务使用更小、更快的模型如Claude Haiku, GPT-3.5-Turbo。对于复杂分析再使用大模型如Claude Sonnet, GPT-4。启用缓存在开发调试阶段务必使用--cache。5. 结构化输出不符合预期原因AI模型可能没有严格按照你定义的Picoschema输出。解决强化指令在提示词中明确强调“你必须严格按照指定的JSON格式输出”。提供示例在提示词中给出一个输出范例。使用更强大的模型像Claude 3.5 Sonnet或GPT-4o在遵循复杂指令方面通常表现更好。后处理可以将AI的输出通过jq等工具进行验证和清洗。例如./runprompt extract.prompt input.json | jq .来检查格式。6.before命令执行失败影响后续流程原因before中的某个Shell命令返回了非零退出码其错误信息stderr被捕获并作为变量值。预防在复杂的before命令后添加错误处理。例如file_count: find . -name *.py 2/dev/null | wc -l将错误重定向到/dev/null。使用条件语句{{#if variable}}在模板中检查变量是否有效避免将错误信息直接传给AI。掌握这些排查技巧能让你在利用runprompt构建复杂应用时更加得心应手。它的设计鼓励探索和组合而一个稳定的工具链是这一切的基础。