Promptheus

Promptheus

优化和完善大模型提示词

快速开始

pip install promptheus

# Interactive session
promptheus

# Single prompt
promptheus "Write a technical blog post"

# Skip clarifying questions
promptheus -s "Explain Kubernetes"

# Use web UI
promptheus web

Python 库用法

from promptheus import refine_prompt

result = refine_prompt("Write a technical blog post", skip_questions=True)
print(result["refined_prompt"])

如果你已经在异步应用（例如 FastAPI）中，请调用 refine_prompt_async，而不是同步辅助函数。

Promptheus 是什么？

Promptheus 会分析并完善你的提示词，具备以下功能：

• 自适应提问：智能识别你需要提供哪些信息
• 多提供商支持：支持 Google、OpenAI、Anthropic、Groq、Qwen 等
• 交互式完善：通过自然对话逐步改进输出
• 会话历史：自动跟踪并重用以往的提示词
• CLI 和 Web 界面：可通过终端或浏览器使用

支持的提供商

提供商	模型	设置
Google Gemini	gemini-2.0-flash, gemini-1.5-pro	API 密钥
Anthropic Claude	claude-3-5-sonnet, claude-3-opus	控制台
OpenAI	gpt-4o, gpt-4-turbo	API 密钥
Groq	llama-3.3-70b, mixtral-8x7b	控制台
Alibaba Qwen	qwen-max, qwen-plus	DashScope
Zhipu GLM	glm-4-plus, glm-4-air	控制台
OpenRouter	openrouter/auto（自动路由）	控制面板

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

• 模型列表有意保持精简：Promptheus 不会显示你 OpenRouter 账户中的完整模型目录。
• 如果你的密钥有访问权限，仍可通过 OPENROUTER_MODEL 或 --model 手动指定具体模型。

核心功能

🧠 自适应任务检测 自动检测你的任务需要完善还是直接优化

⚡ 交互式完善 提出有针对性的问题，以了解需求并改进输出

📝 流水线集成 可在 Unix 流水线和 shell 脚本中无缝使用

🔄 会话管理 自动跟踪、加载并重用以往的提示词

📊 遥测与分析 跟踪匿名使用情况和性能指标以获取洞察（仅本地存储，可禁用）

🌐 Web 界面 美观的界面，支持交互式完善提示词和管理历史记录

配置

创建一个 .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"
# System asks: audience, tone, length, key topics
# Generates refined prompt with all specifications

代码分析

promptheus -s "Review this function for security issues"
# Skips questions, applies direct enhancement

交互式会话

promptheus
/set provider anthropic
/set model claude-3-5-sonnet
# Process multiple prompts, switch providers/models with /commands

流水线集成

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

测试与示例：请参阅 sample_prompts.md，了解用于演示自适应任务检测（分析与生成）的测试提示词。

遥测与分析

# View telemetry summary (anonymous metrics about usage and performance)
promptheus telemetry summary

# Disable telemetry if desired
export PROMPTHEUS_TELEMETRY_ENABLED=0

# Customize history storage location
export PROMPTHEUS_HISTORY_DIR=~/.custom_promptheus

MCP 服务

Promptheus 包含一个 Model Context Protocol（MCP）服务，它将提示词优化功能作为标准化工具开放，以便与兼容 MCP 的客户端集成。

MCP 服务的功能

Promptheus MCP 服务提供：

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

启动 MCP 服务

# Start the MCP server
promptheus mcp

# Or run directly with 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 - 详情请参阅 LICENSE

贡献

欢迎贡献！贡献指南请参阅我们的开发指南。

---

有问题？ 提交 issue | 在线演示： promptheus web