Promptheus

🚀 Promptheus

Promptheus 用于优化大语言模型（LLMs）的提示词，能够对输入的提示词进行分析和优化，提升与大语言模型交互的效果。

🚀 快速开始

使用以下命令安装 Promptheus：

pip install promptheus

以下是一些使用示例：

# 交互式会话
promptheus

# 单个提示词处理
promptheus "Write a technical blog post"

# 跳过澄清问题
promptheus -s "Explain Kubernetes"

# 使用 Web 界面
promptheus web

✨ 主要特性

• 自适应提问：智能检测需要用户提供的信息，通过自适应提问来完善提示词。
• 多提供商支持：支持 Google、OpenAI、Anthropic、Groq、Qwen 等多家大语言模型提供商。
• 交互式优化：通过自然对话的方式迭代改进输出结果。
• 会话历史记录：自动跟踪和复用过去的提示词。
• CLI 和 Web 界面：既可以在终端使用，也可以通过浏览器使用。

📦 安装指南

使用 pip 进行安装：

pip install promptheus

📚 详细文档

支持的提供商

Promptheus 中的 OpenRouter 集成围绕 openrouter/auto 路由模型进行了优化：

• 模型列表经过精简：Promptheus 不会显示完整的 OpenRouter 账户模型目录。
• 如果你的密钥有权限，仍然可以使用 OPENROUTER_MODEL 或 --model 手动指定具体模型。

核心特性

• 🧠 自适应任务检测：自动检测任务是需要细化还是直接优化。
• ⚡ 交互式优化：提出针对性问题，获取需求并改进输出。
• 📝 管道集成：可以无缝集成到 Unix 管道和 shell 脚本中。
• 🔄 会话管理：自动跟踪、加载和复用过去的提示词。
• 📊 遥测与分析：匿名跟踪使用情况和性能指标，以获取洞察信息（仅本地存储，可以禁用）。
• 🌐 网页界面：提供美观的 UI，用于交互式提示词优化和历史记录管理。

配置

创建一个 .env 文件，并至少配置一个提供商的 API 密钥：

GOOGLE_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here

或者运行交互式配置：

promptheus auth

💻 使用示例

内容生成

promptheus "Write a blog post about async programming"
# 系统会询问：受众、语气、长度、关键主题等信息
# 生成包含所有规格的优化提示词

代码分析

promptheus -s "Review this function for security issues"
# 跳过问题，直接进行优化

交互式会话

promptheus
/set provider anthropic
/set model claude-3-5-sonnet
# 处理多个提示词，使用 /commands 切换提供商/模型

管道集成

echo "Create a REST API schema" | promptheus | jq '.refined_prompt'
cat prompts.txt | while read line; do promptheus "$line"; done

测试与示例

请参阅 sample_prompts.md 中的测试提示词，这些提示词展示了自适应任务检测（分析与生成）的功能。

遥测与分析

# 查看遥测摘要（关于使用情况和性能的匿名指标）
promptheus telemetry summary

# 如果需要，禁用遥测功能
export PROMPTHEUS_TELEMETRY_ENABLED=0

# 自定义历史记录存储位置
export PROMPTHEUS_HISTORY_DIR=~/.custom_promptheus

MCP 服务器

Promptheus 包含一个 模型上下文协议（MCP）服务器，它将提示词优化功能作为标准化工具，供与 MCP 兼容的客户端集成使用。

MCP 服务器的功能

• 带问答的提示词优化：通过自适应提问进行智能提示词优化。
• 提示词调整：对现有提示词进行精细修改。
• 模型/提供商检查：发现和验证可用的 AI 提供商。
• 环境验证：检查配置并测试连接性。

启动 MCP 服务器

# 启动 MCP 服务器
promptheus mcp

# 或者直接使用 Python 运行
python -m promptheus.mcp_server

前提条件：

• 安装 MCP 包：pip install mcp（包含在 requirements.txt 中）
• 至少配置一个提供商的 API 密钥（请参阅 配置）

可用的 MCP 工具

refine_prompt

智能提示词优化，可选择是否进行澄清提问。 输入：

• prompt（必需）：要优化的初始提示词
• answers（可选）：问题 ID 到答案的字典 {q0: "answer", q1: "answer"}
• answer_mapping（可选）：将问题 ID 映射到原始问题文本
• provider（可选）：覆盖提供商（例如，"google", "openai"）
• model（可选）：覆盖模型名称

响应类型：

• {"type": "refined", "prompt": "...", "next_action": "..."}：成功优化提示词
• {"type": "clarification_needed", "questions_for_ask_user_question": [...], "answer_mapping": {...}}：需要澄清问题
• {"type": "error", "error_type": "...", "message": "..."}：发生错误

tweak_prompt

对现有提示词进行针对性修改。 输入：

• prompt（必需）：要修改的当前提示词
• modification（必需）：修改描述（例如，"make it shorter"）
• provider, model（可选）：提供商/模型覆盖

返回：

• {"type": "refined", "prompt": "..."}：修改后的提示词

list_models

发现已配置提供商的可用模型。 输入：

• providers（可选）：要查询的提供商名称列表
• limit（可选）：每个提供商的最大模型数量（默认：20）
• include_nontext（可选）：包括视觉/嵌入模型

返回：

• {"type": "success", "providers": {"google": {"available": true, "models": [...]}}}

list_providers

检查提供商的配置状态。 返回：

• {"type": "success", "providers": {"google": {"configured": true, "model": "..."}}}

validate_environment

测试环境配置和 API 连接性。 输入：

• providers（可选）：要验证的特定提供商
• test_connection（可选）：测试实际的 API 连接性

返回：

• {"type": "success", "validation": {"google": {"configured": true, "connection_test": "passed"}}}

带问答的提示词优化工作流程

MCP 服务器支持结构化的澄清工作流程，以实现最佳的提示词优化：

步骤 1：初始优化请求

{
  "tool": "refine_prompt",
  "arguments": {
    "prompt": "Write a blog post about machine learning"
  }
}

步骤 2：处理澄清响应

{
  "type": "clarification_needed",
  "task_type": "generation",
  "message": "To refine this prompt effectively, I need to ask...",
  "questions_for_ask_user_question": [
    {
      "question": "Who is your target audience?",
      "header": "Q1",
      "multiSelect": false,
      "options": [
        {"label": "Technical professionals", "description": "Technical professionals"},
        {"label": "Business executives", "description": "Business executives"}
      ]
    }
  ],
  "answer_mapping": {
    "q0": "Who is your target audience?"
  }
}

步骤 3：收集用户答案

使用 MCP 客户端的 AskUserQuestion 工具处理提供的问题，然后将答案映射到问题 ID。

步骤 4：使用答案进行最终优化

{
  "tool": "refine_prompt", 
  "arguments": {
    "prompt": "Write a blog post about machine learning",
    "answers": {"q0": "Technical professionals"},
    "answer_mapping": {"q0": "Who is your target audience?"}
  }
}

响应：

{
  "type": "refined",
  "prompt": "Write a comprehensive technical blog post about machine learning fundamentals targeted at software engineers and technical professionals. Include practical code examples and architectural patterns...",
  "next_action": "This refined prompt is now ready to use. If the user asked you to execute/run the prompt, use this refined prompt directly with your own capabilities..."
}

AskUser 集成协议

MCP 服务器有两种运行模式：

• 交互式模式（当 AskUserQuestion 可用时）：
  • 通过注入的 AskUserQuestion 函数自动询问澄清问题。
  • 收集答案后立即返回优化后的提示词。
  • 在支持的客户端中提供无缝的用户体验。
• 结构化模式（所有客户端的备用模式）：
  • 返回包含格式化问题的 clarification_needed 响应。
  • 客户端负责调用 AskUserQuestion 工具。
  • 通过 answer_mapping 字典将答案映射回去。

问题格式： questions_for_ask_user_question 中的每个问题包括：

• question：要显示的问题文本
• header：简短标识符（Q1, Q2 等）
• multiSelect：多选选项的布尔值
• options：单选/复选框问题的 {label, description} 数组

答案映射：

• 问题 ID 遵循模式：q0, q1, q2 等。
• 答案字典使用这些 ID 作为键：{"q0": "answer", "q1": "answer"}
• answer_mapping 保留原始问题文本，以供提供商上下文使用。

解决 MCP 问题

MCP 包未安装

Error: The 'mcp' package is not installed. Please install it with 'pip install mcp'.

解决方法：pip install mcp 或使用开发依赖项安装 Promptheus：pip install -e .[dev]

缺少提供商 API 密钥

{
  "type": "error",
  "error_type": "ConfigurationError", 
  "message": "No provider configured. Please set API keys in environment."
}

诊断：使用 list_providers 或 validate_environment 工具检查配置状态

提供商配置错误

{
  "type": "success",
  "providers": {
    "google": {"configured": false, "error": "GOOGLE_API_KEY not found"},
    "openai": {"configured": true, "model": "gpt-4o"}
  }
}

解决方法：在 .env 文件或环境变量中设置缺失的 API 密钥

连接测试失败

{
  "type": "success", 
  "validation": {
    "google": {
      "configured": true,
      "connection_test": "failed: Authentication error"
    }
  }
}

解决方法：验证 API 密钥是否有效，并具有必要的权限

完整文档

• 快速参考：promptheus --help
• 综合指南：
  • 📖 安装与设置
  • 🚀 使用指南
  • 🔧 配置
  • ⌨️ CLI 参考
  • 🌐 Web UI 指南
  • 🔌 提供商设置

开发

git clone https://github.com/abhichandra21/Promptheus.git
cd Promptheus
pip install -e ".[dev]"
pytest -q

详细的开发指南请参阅 CLAUDE.md。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE。

贡献

欢迎贡献代码！请参阅我们的 开发指南 了解贡献准则。

有问题？ 提交问题 | 实时演示：promptheus web