Prompt Decorators

提示词装饰器

📋 目录

• 概述
  • 什么是 Prompt Decorators？
  • 核心组件
  • 背景与动机
  • 提示词工程面临的挑战
  • Prompt Decorators 的优势
  • 主要特性
• 实现状态
• 快速开始
  • 安装
  • 基本用法
• 许可证
• 参与贡献
• 致谢

🔍 概述

什么是 Prompt Decorators？

Prompt Decorators 引入了一套受软件设计模式启发的标准化注解系统，用户可以通过简单、可组合的“装饰器”修改大模型的行为。通过在提示词前添加 +++Reasoning、+++StepByStep 或 +++OutputFormat 等注解，用户可以在不同平台和实现中一致地控制 AI 模型处理请求和响应请求的方式。

本项目通过提供以下内容，应对 AI 交互日益增长的复杂性：

1. 规范：定义装饰器语法、行为和扩展机制的正式标准
2. Python 实现：可用于生产环境的参考实现，配备全面的工具
3. MCP 集成：一种模型上下文协议服务，可在 Claude Desktop 等工具中启用提示词装饰器功能

核心组件

• 📝 规范：提示词装饰器规范（v1.0） 定义了标准
• 🛠️ 核心框架：采用基于注册表的装饰器管理机制的 Python 实现
• 🧩 140 多种装饰器：全面的预构建装饰器库，涵盖推理、格式化等场景
• 🔌 MCP 服务：集成模型上下文协议，可用于桌面 AI 应用
• 🧷 Claude Code 插件：即插即用的 Claude Code 插件，会在模型看到提示词之前，将行内 ::Name(params) 符号扩展为精确指令。附带 /decorate 斜杠命令、常驻配置，以及可选启用的 Haiku 驱动自动选择器。
• 📚 丰富的文档：面向用户和开发者的 API 参考、指南和示例

背景与动机

随着大语言模型越来越多地融入各行各业的工作流，人们逐渐意识到，需要以标准化、一致的方式与这些系统交互。目前的提示词工程方法大多临时拼凑，需要编写大量文档、反复摸索，并且在切换系统或使用场景时会带来显著的认知负担。

提示词装饰器通过简单、可组合的注释，系统地调整 AI 行为，从而应对这一挑战。它们的灵感来自编程中的装饰器模式和 Python 函数装饰器，作为一种抽象层，将核心提示词与处理和呈现响应的指令解耦。

提示词工程面临的挑战

当前的提示词工程存在若干局限：

• 不一致：用户、平台和模型之间的指令差异很大
• 冗长：详细指令会占用本可用于内容的 Token 上下文
• 认知负担：用户必须记住或记录特定的提示词技巧
• 缺乏可组合性：组合不同的指令范式十分繁琐
• 行为未记录：预期的模型行为往往是隐含的，而非明确说明

提示词装饰器的优势

提示词装饰器解决了提示词工程中的关键挑战：

• 不一致：在不同的大模型平台上提供标准语法和统一行为
• 冗长：用简洁的注释取代冗长指令
• 认知负担：通过可复用模式简化提示词编写
• 缺乏可组合性：支持将多种指令范式整洁地组合起来
• 行为未记录：明确规定预期的模型响应

无论你是要针对特定推理模式编写提示词、按特定格式组织输出，还是确保不同模型的响应保持一致，提示词装饰器都能提供一种系统化的方法，让提示词工程更具模块化、可复用性和可维护性。

提示词装饰器框架通过以下方式应对这些挑战：

• 标准化：在不同平台和模型之间采用通用词汇和语法
• 高效性：通过简洁的注释减少 Token 消耗
• 可复用性：行为保持一致，可在不同上下文中复用
• 可组合性：能够组合多个装饰器，以实现复杂的交互模式
• 明确行为：清晰记录预期的模型响应
• 降低认知负荷：用简单注释替代冗长指令

核心功能

• 📚 基于注册表的装饰器管理：集中管理装饰器及其元数据
• ✅ 参数验证和类型检查：稳健地验证装饰器参数
• 🔢 装饰器版本控制：支持装饰器的语义化版本控制
• 🔄 兼容性检查：验证装饰器的兼容性
• 📝 文档生成：自动生成装饰器文档
• 🧩 动态加载：在运行时从定义文件加载装饰器
• 🔍 运行时装饰器发现：动态发现并注册装饰器

💡 实现状态

Prompt Decorators 项目目前正在积极开发中。

你可以通过试用 demo，或将 MCP 服务实现与 Claude Desktop 配合使用，了解提示词装饰器的工作方式。

你也可以在此仓库中使用 .cursorrules，将其作为 Cursor（或 chatGPT/Claude）的系统指令。试试看并分享你的体验！

已实现的功能

• ✅ 核心装饰器注册表：从标准化的 JSON 定义中加载装饰器
• ✅ 装饰器应用：在验证参数的同时，将装饰器应用于提示词
• ✅ 高级转换：将装饰器参数转换为提示词调整
• ✅ 多种输入格式：支持 Python 函数、字符串和 JSON
• ✅ 参数验证和类型检查：稳健地验证装饰器参数
• ✅ 标准装饰器：实现规范中定义的标准装饰器
• ✅ 扩展框架：支持特定领域的装饰器扩展
• ✅ 文档生成：根据装饰器定义自动生成文档

有关实现状态的详细说明，请参阅实现状态文档。

路线图

本项目的路线图详见 ROADMAP 文件。

🚀 快速开始

安装

你可以从 PyPI 安装此软件包：https://pypi.org/project/prompt-decorators/：

pip install prompt-decorators

如需更多功能，可以安装可选依赖项：

# For Model Context Protocol (MCP) integration
pip install "prompt-decorators[mcp]"

# For development and testing
pip install "prompt-decorators[dev,test]"

# For documentation
pip install "prompt-decorators[docs]"

# For all optional dependencies
pip install "prompt-decorators[all]"

基本用法

import prompt_decorators as pd

# Load available decorators
pd.load_decorator_definitions()

# Create a decorator instance
reasoning = pd.create_decorator_instance("Reasoning", depth="comprehensive")

# Apply the decorator to a prompt
prompt = "Explain the concept of prompt engineering."
decorated_prompt = reasoning.apply(prompt)

print(decorated_prompt)

验证安装

安装后，请验证一切是否正常运行：

# Verify the package is installed
python -c "import prompt_decorators; print(prompt_decorators.__version__)"

# Verify registry loading
python -m prompt_decorators verify

如果你看到“Registry verification successful”以及已加载装饰器的数量，就可以开始使用了！

更多示例和使用说明，请参阅官方文档。

📝 许可证

本项目采用 Apache License, Version 2.0 授权。详情请参阅 LICENSE 文件。

🤝 贡献

欢迎贡献！请阅读 CONTRIBUTING 文件，了解如何为本项目作出贡献。

🤖 致谢

本项目的实现离不开以下个人和组织的贡献：

• Mostapha Kalami Heris：感谢他撰写了文章 Prompt Decorators: A Simple Way to Improve AI Responses，该文章启发了这份规范和本仓库
• Synaptiai：本框架和规范的创建者与维护者
• 贡献者：所有为本项目作出贡献的优秀人士