企业官网建设流程全解析

Reflex Build 图片与附件提示（Images and Attachments）实战指南

【免费下载链接】reflex🕸️ Web apps in pure Python 🐍项目地址: https://gitcode.com/GitHub_Trending/re/reflex

图片与附件是 Reflex Build 中把"视觉上下文"交给 AI 构建 Agent 的核心手段：你可以把截图、文档、示例数据直接附进对话，让 Agent 精确还原某个布局，或基于真实数据生成功能。本文以 image_as_prompt.md 为骨架，结合 Reflex 仓库中的相关文档与组件源码，系统讲解附件的三种输入方式、以图作参考的提示词写法、支持的文件格式与大小限制、安全边界，以及让 Agent 生成全新图片的完整流程。读完你将掌握一套可直接复用的"以图生码、以数据生功能"的提示工程方法。

何时需要给 Agent 提供图片或附件

Reflex Build 是一个用自然语言和 Python 构建全栈 Web 应用的 AI 构建器：你可以用一句提示词描述需求，Agent 会规划工作、更新源码、运行应用并在Preview中展示结果（见 What Is Reflex Build）。但纯文字描述布局、视觉层级或数据形态往往模糊且低效，此时就需要借助视觉或基于文件的上下文。

按照原文档的定位，当 Agent 需要"视觉或文件上下文"时，你就应该附加截图、文档或示例数据。典型场景包括：

• 想复刻某个页面的布局、导航宽度、卡片层级与间距；
• 排查一个具体的 UI 问题（如组件错位、间距异常）；
• 让 Agent 基于一份示例 CSV 或文档构建数据导入、预览或校验功能。

附加上下文有三种入口方式，任选其一即可：

1. 点击对话输入框的**附件控件（attachment control）**选择文件；
2. 直接把文件拖拽进对话窗口；
3. 从剪贴板粘贴图片。

以图片为参考：让 Agent 精确还原布局

图片往往是传达"布局、视觉层级、具体 UI 问题"最清晰的方式。原文档给出的核心策略是：明确告诉 Agent 要复制什么、忽略什么，把参考与改动的边界划清楚。

一个标准的参考型提示词示例：

Use the attached screenshot as a layout reference. Match its navigation width, card hierarchy, and spacing, but keep the current brand colors and content.

（把所附截图作为布局参考。匹配它的导航宽度、卡片层级和间距，但保留当前的品牌配色和内容。）

这段提示词遵循了三个原则，值得逐条拆解：

• 明确参考对象：指出附件是"layout reference"，Agent 知道它代表目标形态而非内容素材；
• 列出要复刻的具体维度：navigation width、card hierarchy、spacing 都是可量化的布局要素，比笼统说"做得像它"更容易对齐；
• 划定豁免范围：brand colors 与 content 保持不变，防止 Agent 连配色文案一起改写。

原文档还补充了两条实操建议：

• 截图现有应用时，附上相关路由或页面名（"include the relevant route or page name"），便于 Agent 在多页应用中对号入座，把参考精确应用到对应页面；
• 当只有一个组件重要时，尽量紧贴裁剪（tightly crop）参考图，减少无关元素的干扰，让 Agent 聚焦到真正要复刻的部分。

图片在 Reflex 中的底层呈现：rx.image 组件

"以图为参考"最终落在 Reflex 应用中，往往以rx.image组件承载。从源码看，rx.image实际是 HTML<img>元素（VoidBaseHTML子类Img）的工厂方法别名（image = img = Img.create，见 media.py）。Img组件支持以下常用属性（media.py L81-L114）：

Img.create还做了一项便利处理：用户未显式传src时，会把第一个子节点当作src值使用（media.py L110-L114）。因此当你让 Agent"把截图中的 logo 放进应用"时，Agent 通常会用类似rx.image(src="/logo.png", alt="App logo")的代码把附件落进assets/目录并在页面上渲染——这一点在下一节"附件与运行时资源"中会进一步展开。

附加文件：文档与结构化数据上下文

除了图片，你还可以附加文档和结构化数据。Reflex Build 支持的常见格式（见 Files）包括：

• 文档：.pdf、.doc、.docx、.odt、.rtf
• 电子表格：.xls、.xlsx、.ods、.csv、.tsv
• 演示文稿：.ppt、.pptx、.odp
• 文本与结构化数据：.txt、.md、.markdown、.json、.xml、.yaml、.yml

数量与大小限制（以当前仓库文档为准，具体上传限额请以官方当前页面为准）：

• 普通文件：每个文件最大50 MB，单条消息最多附加20 个文件；
• 图片：Agent 可把.png、.jpg、.jpeg、.webp作为视觉提示上下文理解；每条消息最多5 张，每张最大5 MB（见 Images）。其他图片格式可以当作文件附加进应用，但不会被解释为视觉提示。

原文档强调：附加的数据不要超过任务所需。更小、更聚焦的文件让 Agent 解析更快、更准确。比如要用示例数据构建功能，就只传真正需要的列和行，而不是整库导出。

给每个附件一个明确任务

仅上传文件还不够，你需要告诉 Agent"这份附件应该怎么用"。原文档给出的示例：

Use the attached CSV as sample data. Build an import preview that maps the columns, flags malformed dates, and lets the user exclude invalid rows.

（把所附 CSV 当作示例数据。构建一个导入预览：映射各列、标记格式错误的日期，并允许用户排除无效行。）

这条提示词把"数据用途（sample data）→ 功能目标（import preview）→ 具体行为（列映射、日期校验、排除无效行）"一次性说清，Agent 无需猜测。

附件是提示上下文，不是运行时资源

这是最容易踩的坑：附件只作为提示上下文存在，不会自动成为应用的一部分。原文档明确指出——如果应用需要在运行时"提供或留存"该文件，必须请 Agent 额外添加对应的应用资源（asset）、上传工作流、数据库记录或外部存储集成。

这背后的机制在 Reflex 中有清晰的划分（见 Upload and Download Files）：

• Assets（静态资源）：随应用一起发布的文件（图片、样式表、脚本），位于assets/目录或 Python 文件旁，编译期即可用，通过rx.asset()或直接路径引用；
• Upload Directory（上传目录）：运行期由用户上传的动态文件，位于uploaded_files/（可配置），通过rx.get_upload_url()访问。

所以当你让 Agent"用附件中的 CSV 做导入"时，正确的做法是让 Agent 用rx.upload组件 + 上传事件处理函数把 CSV 作为运行时文件接收，再用 Python 在事件处理器中解析——附件本身只负责把"数据结构长什么样"这个上下文传递给 Agent。

提示词进阶：把附件意图说清楚

综合 Images 与 Files 两页的指导，写附件提示词时建议明确回答三个问题：

1. 它是视觉参考，还是要提取的内容，还是需要保留的现有资源？三种意图对应完全不同的 Agent 行为——参考意味着"照着画"，提取意味着"读出来写进代码"，保留意味着"原样放进应用别改"；
2. 复制什么、忽略什么？把要复刻的维度（布局、层级、间距、配色）与要排除的内容（现有文案、品牌色、无关区块）分开声明；
3. 它只是上下文，还是运行时要用的数据？若是后者，明确要求 Agent 补上 asset、上传工作流、数据库或存储集成。

另外，Reflex Build 支持排队后续指令：Agent 生成过程中你可以继续发送消息，它会下一步拾取（见 Generation Controls & Collaboration）。这意味着你可以先用一句"用这张截图调整首页布局"启动生成，再排队补充"表格在 768px 以下要响应式"这类小约束，而不必等整轮结束。

生成新图片：从"参考"到"原创"

如果应用需要的是原创视觉（hero 背景图、插画、占位图），而不是对现有图片的复刻，可以直接请 Agent 生成。这是 Reflex Build 内建的 Agent 工具之一（另两项是联网搜索与运行 Python，见 Agent Tools）。生成的图片会出现在对话与应用变更中，无需离开 Builder 去外部工具。

原文档建议在提示词中描述预期用途、构图与约束，示例：

Generate a wide, abstract hero background for a financial dashboard. Use navy and teal, leave the left third visually quiet for heading text, and do not add words, logos, or interface elements.

（为金融仪表盘生成一张宽幅抽象 hero 背景。使用海军蓝与青绿色，左侧三分之一保持视觉留白用于标题文字，不要添加文字、logo 或界面元素。）

注意这条提示词的约束密度：配色（navy/teal）、构图（左侧留白）、禁区（无文字/logo/界面元素）全部显式声明，Agent 就不容易"自由发挥"出不可用的素材。

生成之后，原文档建议按以下清单审查：

1. 在Preview中以目标尺寸查看图片；
2. 确认叠加在图片上的文字依然清晰可读；
3. 检查移动端的裁剪与加载行为；
4. 若构图或风格不对，请求一次聚焦的修改（focused revision），而不是推倒重来。

安全与隐私边界

无论附加还是生成，安全红线必须遵守（详见 Secrets 与 Agent Tools 的 Security and Privacy 一节）：

• 不要把密码、API 密钥、私有 token 或生产环境凭证写进提示词或附件；凭证应存放在Secrets（应用/项目级环境变量，运行时通过os.environ读取）或集成表单中；
• 不要要求 Agent 搜索或复现私有数据；附件若含私有生产导出，除非已获准用于 Reflex Build，否则不要附加；
• 发布前审查：检查生成资源与第三方信息（联网搜索结果、附件内容），确认无敏感信息外泄或错误内容被带入应用。

一旦在附件中发现敏感值，后续生成会持续把该上下文带在对话中，因此"先删后问"比"先问后删"更安全。

端到端示例：从截图到可运行页面

把以上要点串成一个完整流程（基于原文档与 What Is Reflex Build 的典型工作流）：

1. 附加参考：拖入目标应用首页的截图（裁剪掉无关区块），并在消息中写明路由（如/dashboard）与页面名；
2. 声明意图：用"Use the attached screenshot as a layout reference. Match its navigation width, card hierarchy, and spacing, but keep the current brand colors and content."明确复制范围与豁免项；
3. 补充数据上下文（可选）：再附一份小 CSV 并说明它只是示例数据，请 Agent 构建带校验的导入预览；
4. 排队微调：生成过程中补充"表格在移动端改为纵向堆叠"之类的后续指令；
5. 预览验证：在Preview中按目标尺寸检查还原度、响应式表现与加载行为，必要时请求聚焦修改；
6. 审查发布：确认无敏感信息，再走测试、部署流程。

若最终页面需要展示某张图，可让 Agent 用rx.image(src=..., alt=..., loading="lazy")将其加入应用（组件属性详见 media.py），并确保图片作为assets/资源随应用发布，而非仅存在于对话上下文。

小结

图片与附件是 Reflex Build 提示工程中最具杠杆作用的一环：截图解决"长什么样"，文件解决"数据长什么样"，生成解决"没有现成素材怎么办"。记住三条主线即可——附件只是上下文、不是运行时资源；提示词要同时声明"复制什么"与"忽略什么"；敏感信息走 Secrets 而不是 prompt。配合 Agent Tools、Files、Images 与 Secrets 四篇文档，你就能把视觉与数据上下文稳定地转化为高质量的应用代码。

【免费下载链接】reflex🕸️ Web apps in pure Python 🐍项目地址: https://gitcode.com/GitHub_Trending/re/reflex