groq-appgen代码剖析：constructPrompt提示词模板的设计与实现原理-开发者社区

groq-appgen代码剖析：constructPrompt提示词模板的设计与实现原理

【免费下载链接】groq-appgenProject showcasing Llama 3.3 70B HTML codegen abilities项目地址: https://gitcode.com/gh_mirrors/gr/groq-appgen

groq-appgen 是一款基于 Groq 平台与 Llama 3.3 70B 大模型的 AI 应用生成器，能把一句自然语言描述变成一个可运行的 HTML 微应用。它把用户需求"翻译"成代码的核心，是一个动态组装提示词的函数——constructPrompt。本文将剖析这个提示词模板的设计思路与实现原理。

一、项目背景：从"一句话"到"一个完整网页"

groq-appgen 的工作流程非常直观：用户在输入框描述想要的功能（也可以手绘草图或语音输入），后端调用大模型，实时流式地生成一个完整的 HTML 页面，并支持后续不断反馈修改。

整个系统的技术栈是 Next.js 14 + TypeScript + Groq SDK，详见 README.md。而在所有链路中，真正决定"模型该输出什么"的，是 src/utils/prompt.ts 中仅 30 来行的constructPrompt函数——它把零散的用户意图，组装成一份结构严谨的提示词模板。

二、constructPrompt 的四个输入：一个"提示词配方"

constructPrompt接收一个PromptData对象，包含 4 个全部可选的字段（见 src/utils/prompt.ts#L1-L6）：

字段	含义	触发场景
`query`	用户的自然语言需求	首次生成应用
`currentHtml`	当前版本的页面代码	迭代修改时
`currentFeedback`	用户对当前版本的修改意见	迭代修改时
`theme`	主题偏好（dark / light / 空）	跟随用户系统主题

💡设计要点：四个字段全部可选，意味着同一个函数可以同时服务"从零创建"和"持续修改"两种模式，而不用写两套提示词逻辑。

三、条件组装：模板只包含"相关"的部分

函数内部采用条件拼装策略，按顺序尝试注入四个区块（见 src/utils/prompt.ts#L14-L27）：

1️⃣ 上下文区块—— 只有存在currentHtml时，才把现有页面代码包裹进<current html>标签，告诉模型"这是你正在修改的东西"。

2️⃣ 反馈区块—— 只有存在currentFeedback时，才把用户意见放进<feedback>标签。

3️⃣ 查询区块—— 关键互斥逻辑：!hasFeedback && query。当用户给出修改意见时，不再携带原始 query——因为此时任务已从"创建"变成"按反馈改"，旧需求反而会干扰模型，浪费 token。

4️⃣ 输出指令区块—— 无条件存在，是整份模板的"契约"。

最后用.trim()收尾，避免多个空行残留。这种"按需组装"让提示词始终保持最小长度：新建场景下不含 HTML 上下文，修改场景下不含重复的需求描述。

四、输出契约：为什么强调 ```html 三重反引号

<output instructions>区块看似简短，实则约束了整条链路的三个关键点（src/utils/prompt.ts#L17-L26）：

单文件约束：明确要求 "Generate asingleHTML file"，杜绝模型拆分出多个文件；
技术栈锁定：强制使用 Tailwind CSS，且必须通过<head>中的 CDN 脚本引入，保证生成结果开箱即用、无需构建步骤;
格式契约：要求输出用```html三重反引号包裹。

这个"格式契约"并非写给人类看的——它是给程序看的。服务端在 src/app/api/generate/route.ts 中用正则```html\n([\s\S]*?)\n```精确截取代码块内容，剥离模型的"寒暄语"，把纯 HTML 返回给前端渲染。提示词与解析代码互为镜像，缺一不可。

五、主题感知：一段三目运算的巧思

模板还内置了无障碍（Accessibility）约束。themeInstructions用一段三目运算（src/utils/prompt.ts#L12）生成三种指令：

dark→ "使用深色背景 + 浅色文字"
light→ "使用浅色背景 + 深色文字"
其他 → "使用中性的、两种模式下都好看的配色"

无论哪种情况，都追加一句"确保颜色对比度良好且无障碍"。这个细节让同一份模板能适配明暗两种界面环境，而不是硬编码死一种配色。

六、模板的两个消费场景：服务端生成 + 客户端透明面板

constructPrompt在项目中有两处调用，恰好体现了"一份模板、两种用途"的设计：

🔧 场景一：服务端生成管道

generate 路由在POST /api/generate中组装提示词，随后串联完整的工程化流程：

若用户上传了手绘草图，先调用视觉模型生成文字描述，追加进 query（画得越好，生成越准）；
用 LlamaGuard 3 8B 做内容安全检查，违规直接 400 拦截；
流式或非流式请求模型，并内置 generateWithFallback 降级机制：主模型失败自动切换备用模型（模型参数配置在 src/utils/models.ts）。

🔍 场景二：客户端透明调试面板

更有趣的设计在 studio-provider.tsx：前端把constructPrompt的输出通过getFormattedOutput()暴露出来，并在 studio-view.tsx 的侧滑调试面板中实时展示。用户能亲眼看到"发给模型的那段话长什么样"。

这种提示词透明化的设计是新手学习提示词工程的绝佳教材——你可以实时对比：改动一句反馈后，最终提示词如何随之变化。

七、5 个值得借鉴的提示词工程技巧 ✨

结构分隔符：用<current html>、<feedback>、<query>这类 XML 风格标签区隔不同来源的内容，模型不易混淆"用户说的"和"系统要求的"；
互斥裁剪：有反馈时丢弃旧需求，提示词只保留当前任务最相关的信息，省钱又提效；
契约化输出：把"输出必须长什么样"写成可程序化解析的格式，让 AI 输出成为可靠的 API 数据源；
无副作用约束：锁定单文件 + CDN 引入的技术栈，让生成结果零依赖、零构建直接可运行;
单一数据源：同一个函数既用于真实请求，也用于调试展示，保证"你看到的"永远等于"发出去的"，杜绝两处维护漂移。