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