Deck by PromptPHP：让 AI 提示词像代码一样版本化管理

作者：Victor Ukam（PromptPHP 团队）| stars: 104 | 语言: PHP | 许可: MIT

Deck 官方品牌图，展示其作为 Laravel AI 提示词管理工具的定位。

一个真实的痛点场景

想象你维护着一个电商客服 AI Agent，"请用礼貌的语气总结订单"这条指令在 v1 用了 3 个月，效果不错。某天产品经理说"语气要更专业"，你随手改了 Prompt。一个月后发现客服好评率下降了——但你根本说不清楚是哪个改动导致的，因为 Prompt 存在数据库里，连版本记录都没有。

Deck 正是为了解决这个问题而生。它把 AI 提示词从数据库字段变成文件系统里的 .md 版本文件，让提示词拥有和代码一样的 Git 版本控制能力——你可以随时切换、回滚、对比 A/B 测试不同版本的 Prompt 效果。

项目背景：从 Prompt Deck 到 Deck

Deck 原名 "Prompt Deck"，由尼日利亚开发者 Victor Ukam 创建和维护，后更名为 Deck by PromptPHP，发布在 promptphp/deck 仓库。项目托管于 GitHub（104 ★），主分支为 0.x（语义化版本尚未进入稳定版），遵循 MIT 许可证。

PromptPHP 团队专注于 Laravel 生态的 AI 工具链，Deck 是其核心产品之一，深度集成 Laravel AI SDK（laravel/ai），并于 2026 年初获得了 Laravel News 的专题推荐，被收录进 Laravel 生态的 AI 工具精选列表。

核心功能：把 Prompt 变成版本化的文件资产

文件即 Prompt，Git 即版本控制

Deck 的核心理念是：Prompt 是文件，不是字段。通过 php artisan make:prompt order-summary 命令，在 resources/prompts/ 下自动创建版本化目录结构：

resources/prompts/order-summary/
├── metadata.json          # Prompt 名称、描述、当前活跃版本
├── v1/
│   ├── metadata.json      # 本版本元信息
│   ├── system.md          # system prompt（AI 的角色设定）
│   ├── user.md            # user prompt（用户输入模板）
│   └── assistant.md       # assistant prompt（AI 回应模板）
└── v2/                    # v2 草稿，不影响线上流量

每个版本下的 .md 文件天然支持 {{ $variable }} 变量插值语法，渲染时自动替换为实际值。这种设计让 Prompt 具备了：

• 版本隔离：新版本草稿不影响线上流量，可随时激活切换
• 角色分离：system / user / assistant 分离存放，职责清晰
• Git 版本控制：随意回滚 diff，commit 历史清晰可见
• 变量插值：模板变量在渲染时动态替换，无需字符串拼接

A/B 测试与性能追踪

启用数据库追踪后，Deck 自动记录每次 Prompt 执行的耗时、Token 消耗、输入输出内容。通过 php artisan prompt:list --all 可以查看不同版本的流量分布，对比哪个版本的 Prompt 效果更好——这是传统 Prompt 管理方案中极难实现的能力。

Laravel AI SDK 深度集成

当项目安装了 laravel/ai 包时，Deck 可以自动将提示词加载到 AI Agent 中，无需手动调用 Deck::get()。运行 php artisan make:agent 时，Deck 会自动创建对应的提示词目录，真正做到"开发 Agent 时 Prompt 同步生成"。

技术架构

Deck 是典型的 Laravel Package（Composer 库），核心依赖：

依赖	作用
illuminate/* (Laravel 核心)	框架集成、服务提供者、依赖注入
nesbot/carbon	时间处理（追踪记录时间轴）
sebastian/diff	版本间 diff 对比
illuminate/database	追踪数据持久化

核心类：

• PromptManager：加载、缓存、渲染 Prompt 的主入口
• PromptTemplate：变量插值引擎，处理 {{ $var }} 语法
• TrackPromptMiddleware：中间件，拦截 AI 请求记录执行数据
• PromptExecution / PromptVersion：Eloquent 模型，对应追踪表和版本表

代码质量方面，项目使用 Pest 单元测试框架（而非 PHPUnit 原生），配合 Laravel Pint 做代码风格检查，有完整的架构测试（tests/Architecture），自动化程度较高。

上手体验

安装只需一行命令：

composer require promptphp/deck
php artisan vendor:publish --provider="PromptPHP\Deck\Providers\DeckServiceProvider"
php artisan migrate  # 可选：启用追踪功能

创建第一个 Prompt：

php artisan make:prompt order-summary
# 编辑 resources/prompts/order-summary/v1/system.md
# 写上：你是{{ $tone }}风格的客服，总结订单：{{ $order }}

# 使用
$prompt = Deck::get('order-summary');
$messages = $prompt->toMessages(['tone' => '友好', 'order' => $orderData]);
# 传入任意 LLM API（OpenAI、Anthropic 等）

升级到新版本时：

php artisan make:prompt order-summary  # 再次运行
# 选 [version] 创建 v2
# 确认 v2 效果后：
php artisan prompt:activate order-summary v2

文档站点（deck.promptphp.com）使用 Mintlify 构建，有完整的 Getting Started 和 Advanced 指南。

局限与注意事项

1. 仅限 Laravel/PHP 生态：Deck 深度绑定 Laravel，如果你的项目不是 PHP/Laravel，目前无法使用。Laravel 之外的开发者可关注类似理念的 promptfoo（Node.js）、PromptLayer（Python）等工具。

2. 0.x 阶段 API 尚未稳定：主分支为 0.x，说明仍处于快速迭代期，重大 API 变更可能影响升级路径（作者提供了从 v0.3.x 到 v0.4.0 的迁移指南）。

3. 无容器化支持：作为 Laravel Composer 包，不提供 Dockerfile 或 docker-compose.yml，无法通过容器一键部署，需要在已有 Laravel 环境中通过 Composer 安装。

4. 追踪功能依赖数据库：性能追踪和 A/B 测试需要开启数据库追踪，裸装环境（无数据库）只能使用基础的 Prompt 管理和渲染功能。

5. 不支持纯客户端使用：Deck 是一个服务端 Composer 包，不适合纯前端 JavaScript 项目或桌面应用场景。

行业意义

随着大模型应用在企业场景的深入，Prompt 工程化 正在从"调调试试"走向"工程化管理"。Deck 率先在 Laravel 生态引入了"Prompt 即代码"的理念——将提示词版本化、文件化、可追踪化，解决了 AI 应用团队在生产环境中管理 Prompt 的核心痛点。

这种思路正在向其他语言生态扩散：Python 领域有 prompttools、promptlayer，Node.js 领域有 promptfoo，但 Deck 在 Laravel 集成深度和 A/B 测试追踪方面做得尤为细致。

随着 AI Agent 应用的普及，对 Prompt 的版本控制、性能追踪灰度发布需求会越来越强，Deck 这类工具的价值将持续凸显。

项目 CI 检查全部通过，展示良好的代码质量维护状态。