Replit Agent内部提示词与JSON配置详解：AI程序员一句话生成软件

本教程将深入探索 Replit Agent 这款强大的 AI 编程助手，详细剖析其内部提示词的结构与工作原理，帮助您理解它如何根据简单描述自动生成完整的应用和代码。

认识 Replit Agent：AI 驱动的编程开发环境

在深入分析其提示词之前，我们先来了解一下这款产品。Replit Agent 本质上是一个集成了人工智能的编程开发环境（IDE）。它的核心功能是，您只需在对话框里用一句话描述您想要实现的编程功能，AI 袋里便会自动生成相应的代码和整个项目文件。

• 一键部署与展示：Agent 不仅能生成代码，还能直接在 Replit 平台上部署服务。每个生成的应用都可以直接看到最终的渲染形态，让您即时验证结果。
• 团队协作：您还可以邀请团队成员一起查看或修改项目。
• 免费用户限制：免费用户最多可以创建 3 个应用，并拥有 10 个检查点（checkpoint）。注意，每次与 Agent 对话并执行操作（无论是修改功能还是重新生成应用）都会消耗 1 个 checkpoint。

当您下达指令后，Agent 会判断应用的类型和所需功能，例如是否需要集成 OpenAI 的 API 或网页抓取工具。它会制定一个执行计划，并逐步执行。如果过程中需要您填写 OpenAI API Key 等关键信息，Agent 会暂停并询问，而您的回答 不会 消耗 checkpoint。

01 Replit Agent 工具配置文件（tool.json）结构解析

Replit Agent 的提示词由两个核心文件构成：一个是描述工具的工具配置文件（tool.json），另一个是总体行为指导的 prompt.txt 文件。我们先来详细解析 tool.json。这个文件按功能相似性和执行流程顺序组织了各种工具，大致框架如下。

核心工作流：文件管理与工作流控制

文件的第一个工具是 restart_workflow，第二个是 search_filesystem。这两个工具用于 Replit Agent 应用的修改流程。例如，当您需要在右边的界面打开并编辑一个 .py 文件，修改完成后，Agent 会使用 restart_workflow 来重启应用（如 Streamlit）。

之所以将文件搜索编辑和启动/重启工作流放在前列，是因为对于一键生成应用的编程产品，持续与用户沟通和修改是常态，而不是一次就做到完美。其中，restart_workflow 工具也涵盖了 start workflow，即第一次对话启动工作流的功能。

文件管理模块（File Management）

此模块用于在代码库中搜索和管理文件。

• search_filesystem：用于在代码库中搜索相应文件。支持的搜索方式包括：
  • class_names（按类名搜索）
  • code（按代码片段搜索）
  • function_names（按函数名搜索）
  • query_description（使用自然语言查询，执行语义相似性搜索，适用于更复杂的需求，例如：“查找数据库连接的错误处理”）

{
  "class_names": ["UserAuth", "Authentication"],
  "function_names": ["login", "authenticate", "verifyToken"],
  "query_description": "查找用户认证和授权的实现代码"
}

• str_replace_editor：此工具用于在多轮交互中持久地查看（view）、创建（create）、字符串替换（str_replace）、插入（insert）和撤销（undo_edit）文件。您需要配合 search_filesystem 来使用它来查看和编辑文件。

• repo_overview：此工具用于概括性地描述代码仓库的主要功能、模块和结构等信息。在进行检索之前，Agent 会先查看文件系统和 repo_overview，然后再使用 search_filesystem 进行本地检索。

小提示：文件目录直接以 root 权限为基础，并且 Replit 提示词要求路径必须是相对路径。

代码环境模块（Code Environment）

此模块用于管理项目的依赖和运行环境。

• packager_tool：其参数是先获取依赖列表（dependency_list），然后执行安装或卸载（install_or_uninstall）操作。您需要指定所使用依赖工具的编程语言（language_or_system）。例如，Agent 在安装 openai 库时会用到此工具。

• programming_language_install_tool：用于安装编程语言和系统环境。特别适用于程序无法运行时，例如因 Python 版本不对导致的问题。
• bash：提供运行 Linux Bash 命令的能力。适用于脚本执行、包安装、文件操作、服务启动等任务。参数包括要运行的 bash 命令（command）和是否重启工具环境（restart）。

PostgreSQL 数据库管理模块

此模块用于管理和操作 PostgreSQL 数据库。

• create_postgresql_database_tool：用于创建一个供项目使用的 PostgreSQL 数据库。创建成功后，会生成一系列环境变量（如 DATABASE_URL, PGPORT, PGUSER, PGPASSWORD, PGDATABASE, PGHOST）供项目连接数据库使用。
• check_database_status：用于检查已创建的数据库是否可用和可连接。
• execute_sql_tool：使用 SQL 查询对数据库进行查看、插入、更新等操作，常用于调试错误或访问数据库结构。此工具被配置了 3 个使用规则：
  1. 优先使用此工具修复数据库错误，而不是手动写如 db.drop_table() 的代码。
  2. 使用标准 SQL 语法编写清晰、格式良好的查询语句。
  3. 用于数据库交互、数据操作、查询优化。

小提示：免费用户拥有 10GB 的 PostgreSQL 存储空间。

工作流模块（Workflow）

此模块用于控制和管理 Agent 的工作流程与用户交互。

• workflows_set_run_config_tool：在项目开始时，此工具会在后台生成一个任务表，适用于开发服务器、构建流程或任何需要长期运行的进程。其参数包括：
  • name：标识每个任务的名称。
  • command：要执行的 shell 命令。
  • wait_for_port：填写具体需要监听的端口，用于让 Agent 确认端口是否准备好。

例如，启动一个 Node.js 服务器：

{
  "name": "Server",
  "command": "npm run dev",
  "wait_for_port": 5000
}

• workflows_remove_run_config_tool：用于删除之前配置过的后台任务，参数只有任务名称 name。

• report_progress：用于向用户报告已完成的事项和正在进行的任务。只有当用户确认某个主要任务已完成时，Agent 才可以调用此工具。调用后，它会生成一段简洁的进展总结，并主动询问用户下一步要做什么。具体规则包括：
  • 必须等待用户确认完成任务后才能使用。
  • 一次只能总结 5 个事项以内。
  • 使用简单、日常用语，不使用专业术语。
  • 每个完成项前加 ✅，进行中项前加 ➡。
  • 最后一行一定要问：“下一步做什么？”

下图黄色笔记高亮的区域就是 report_progress 在使用时的具体行为。

• suggest_deploy：此工具没有参数。当 Agent 觉得项目开发已完成时，会调用此工具告知用户“你的项目已经准备好可以部署了”。调用后，部署流程将交由 Replit Deployments 自动完成，Agent 无需再操作或检查。具体规则描述：
  • 只有在确认项目能正常运行、功能已完成时调用。
  • 当用户主动提出“现在部署项目”时，立即调用。

重要提示：调用此工具 不会 真正部署项目，而是 建议 用户进行部署。真正的部署需要用户手动点击确认。Replit 会自动完成编译打包、托管服务器设置、HTTPS 配置、运行检查等一系列操作。部署成功后，项目将出现在 yourproject.replit.app。注意，部署功能需要订阅计划付费升级才能使用。

应用反馈模块（Application Feedback）

Replit Agent 提供了三类 application_feedback_tool，用于向用户展示不同应用类型的运行效果并收集反馈。

• web_application_feedback_tool：用于确认 Web 应用是否已成功运行。它会访问指定的网页路由（如 /dashboard）、捕获网页截图、查看日志确认运行情况。如果运行成功，就会展示网页界面并询问用户是否满意或继续调整。
  • 参数 query：要问用户的问题（例如：“您对这个界面满意吗？”）。
  • 参数 website_route：可选，用于指定网页路径（如 /products/list）。
  • 参数 workflow_name：必填，用于识别是哪个 Workflow 提供了这个 Web 服务。

下图是 Agent 完成 report_progress 后，利用 web_application_feedback_tool 截图检查，并输出类似 report_progress 风格的总结。其对 query 参数的描述要求与 report_progress 类似，例如一次总结不超过 5 个事项，使用简单日常用语等。

• shell_command_application_feedback_tool：用于运行 CLI 或交互式命令行应用，并收集用户对行为或输出的反馈。
  • 参数 shell_command：要运行的命令，如 python app.py。
  • 参数 query：Agent 要问用户的问题。
  • 参数 workflow_name：在哪个 workflow 下执行命令。
• vnc_window_application_feedback：用于运行需要图形界面（GUI）显示的桌面应用。通过 VNC（远程桌面）将界面展示给用户并收集反馈。它可以运行 PyGame、Tkinter、OpenCV 等桌面窗口程序，并检查键盘、鼠标事件是否生效，窗口视觉行为是否符合预期。
  • 参数 vnc_execution_command：用于启动窗口程序的命令。
  • 参数 query：要问用户的问题。
  • 参数 workflow_name：在哪个 workflow 下执行命令。

这三个工具都类似于 feedback_tool，需要主动询问用户 query 和 workflow_name，区别在于一个检查网络端口，一个检查 shell 命令，一个检查虚拟桌面 VNC。

关于 Workflow 的提示词显示，这三个 application_feedback_tool 非常重要，它们控制着最初的 restart_workflow。Agent 不需要手动重启，而是根据这些反馈工具收集的用户需求自动重启，这包括网页应用的端口分配和其他命令的执行。每一步的执行既需要整理目前所有可参考的信息，又需要再次确认 feedback_tool。

密钥管理模块（Secrets）

由于经常需要生成需要 LLM 和搜索 API 的应用，因此需要一个安全上传密钥并添加到环境变量中的工具。

• ask_secrets：当 Agent 检测到某个关键的 API 密钥尚未提供时，会调用此工具向用户请求填写。参数包括 user_message（给用户的提示语，说明为什么需要这些密钥）和 secret_keys（要请求的密钥名称列表）。
• check_secrets：用于检查某个密钥是否已存在于当前环境变量中。它不返回具体值，只返回是否存在。这两个工具通常搭配使用。

例如，当您请求 Agent 修改为使用 OpenAI Compatible API 时，Agent 会说“请提供这两个值，我们将更新代码以使用 xxx”，随后出现填写栏，这属于 ask_secrets 工具的功能。

其他标签（Labels）

tool.json 文件最后还有一些标签。

其中 policy_spec 和 important 的内容与 prompt.txt 中的内容相关。下面我们将正式开始梳理 Replit Agent 的 prompt.txt 提示词文件。

02 Replit Agent 总提示词（prompt.txt）详解

这个提示词文件除了包含“Operating Principles”（操作原则）外，其他各部分在上文的 workflow 小节中已经提及。由此可见，主要的提示词都是针对 Replit Agent 的工作流、每个步骤所需的检查以及每个工具的使用条件而设计的。

核心原则：遵守工具，避免过度干预

• 优先使用已有工具：既然已经有了 tool.json 文件，Agent 应尽可能使用已有的 Replit 工具，而不是自己创建新的，例如禁止创建容器和虚拟环境，这会增加项目复杂度。
• 明确工具作用：例如，查看 PostgreSQL 数据库，就必须使用 tool.json 中的 execute_sql_tool。
• 保持环境纯净：整体上，编程的严格性要求 Agent 不允许随意删除或更新内容，也不允许未经用户许可的随意操作。

编辑与最佳实践

下面截图中的“editing files”和“best Practice”部分同样是在指导工具何时使用。

调试流程：系统化排查

在调试过程中，Agent 需要利用系统自动生成的日志（automatic_updates）和专门针对浏览器的日志（webview_console_logs）进行排查。除此之外，还需要深入分析问题的根本原因（root cause），并结合相关文件（如本地文件、feedback_tool 截图、数据库状态等）进行分析。如果尝试 3 次后仍无法解决，再询问用户。

用户沟通政策

• 范围限制：与用户的交互应专注于解决编程需求和简单的问答。对于付费、会员等商务问题，Agent 不允许代替 Replit 公司回答。
• 语言要求：遵循“Communication Policy”，使用用户能理解的语言进行交流。
• 功能操作：对于 rollback（回滚）、API key 输入、deploy（部署）等操作，只能让用户使用相应的功能按钮来完成。

主动策略

• 主动询问：这是由“Proactive Policy”定义的。一些细碎的日志和警告不需要让用户知道，除非用户主动要求。只有当发生重大更新（如改变 API）时才主动询问用户。
• 避免打扰：对于一些状态信息和日志，不要主动询问用户。用户只提问问题，如果用户的指令与代码执行无关，Agent 只回答用户问题，并时刻跟随用户的指令。

数据完整性

• 减少幻觉：“data integrity Policy”用于确保 Agent 的回答不是凭空捏造的，都有来自真实 API 的真实来源，以最大限度地减少模型幻觉（hallucination）现象。
• 诚实原则：如果确实回答不出来，Agent 必须直接报错，并且报错信息要写详细、具体，而不是给出一个看似合理的虚假回答。

常见问题（FAQ）

1. 问：免费用户有哪些主要限制？
   答：免费用户只能创建 3 个应用，拥有 10 个 checkpoint。每次与 Agent 对话并执行操作（如修改功能或重新生成应用）都会消耗 1 个 checkpoint。
2. 问：如果我修改了代码，如何重新启动我的应用？
   答：您不需要手动操作。Agent 会自动使用 restart_workflow 工具来重启应用。它通过 application_feedback_tool 收集您的反馈，并根据这些反馈来触发重启流程，包括重新分配端口等。
3. 问：如何安全地将我的 API Key 提供给 Agent？
   答：当 Agent 检测到需要 API Key 时，它会调用 ask_secrets 工具。在用户界面上会弹出一个专门的填写栏，您可以在此安全地输入您的密钥。Agent 会将密钥存储为环境变量，不会在对话中明文显示。
4. 问：Agent 在什么情况下会主动询问我问题？
   答：Agent 只会主动询问您两种类型的问题：1）在完成任务后，通过 report_progress 或 application_feedback_tool 询问您是否满意或下一步做什么；2）当它需要关键信息（如 API Key）或认为项目已准备好部署（调用 suggest_deploy）时。对于细碎的日志或警告，Agent 不会主动打扰您。

小贴士与最佳实践

• 清晰描述需求：在对话框中，您的描述越清晰、具体，Agent 生成的代码和项目就越符合您的预期。例如，明确指出需要集成哪些第三方服务（如 OpenAI、数据库等）。
• 善用暂停功能：当 Agent 在执行计划中需要您填写密钥或确认时，它会暂停并等待您的输入。这不会消耗 checkpoint，请放心使用。
• 理解 Checkpoint 消耗：每次 Agent 执行一次操作（无论是生成、修改还是调试）都算作一次对话，并消耗一个 checkpoint。建议在与 Agent 交互前，先在脑海中规划好需求，以避免不必要的消耗。
• 利用文件搜索功能：如果您想基于现有文件进行修改，可以清晰地描述您想修改的文件或功能，Agent 会使用 search_filesystem 和 str_replace_editor 等工具高效地完成任务。

你是一名 AI 行业编辑，请围绕下面这条热点输出一份资讯解读：
热点：Replit Agent内部提示词与JSON配置详解：AI程序员一句话生成软件要求：
1. 先用一句话解释这条热点在讲什么
2. 再总结它为什么重要
3. 说明会影响哪些 AI 产品或内容方向
4. 最后给出 3 个适合资讯站使用的标题