配置页面剧本（页面感知型聊天启动器）

原则——开场白是唯一保证被阅读的句子。 通用的“我能帮您什么？” 会让页面访问变得毫无意义。而剧本（playbook）能让同一个智能体在每个页面上以不同的方式开场，并且已经知道访客身处何地。更多信息见 页面剧本。

页面剧本 是附加在 URL 模式上的简短简报。它包含三个部分：

• context —— 智能体的私有背景信息，不显示给访客（谁访问了这个页面，他们在决定什么，他们通常担心什么）。请撰写背景信息，而非事实：价格、配额和政策应放在 知识库 中，其优先级高于背景信息。
• greeting —— 访客实际看到的开场白。
• questions —— 最多四个建议问题，以便尚未形成想法的访客可以直接选择。

正确的剧本是根据 URL 选择的：解析顺序为 显式 key → url_pattern → 默认值。单个默认值捕获所有未匹配的页面，因此永远不会回退到空白框。

1. 查看现有内容

list_page_contexts()   # existing playbooks: match rules, greeting mode, position, which is default

2. 创建或替换

upsert_page_context(
  key="pricing",
  label="Pricing page",
  url_pattern="*/pricing",           # glob, path-only; ignores query string and trailing slash
  context="Visitors here are comparing plans and worrying about overage. "
          "They are usually the person who will sign off on the cost. "
          "Do not quote custom pricing in chat.",
  greeting="You're looking at our plans — want me to work out where overage would start for your volume?",
  questions=["What's included in the free plan?", "How is overage billed?", "Can I change plans later?"],
  greeting_mode="generated",         # generate opener + questions in the visitor's language (recommended)
  is_default=False,
)

greeting_mode="generated" 会根据访客的语言动态生成开场白和问题——因此西班牙语访客会收到西班牙语开场白，而无需您编写五个版本。仅在您希望 greeting/questions 完全按字面意思显示时使用 "static"。

3. 验证匹配——始终执行

resolve_page_context(url="https://acme.com/pricing?ref=x")   # → which playbook this URL hits, and how

Glob 模式很容易出错（缺少 *，路径层级过多）。匹配失败没有错误消息——访客只是静默地获得默认剧本。因此，在编写任何 url_pattern 后，解析一个真实 URL 并确认 matched_by 是 url_pattern，而不是 default。

4. 设置通配默认值

upsert_page_context(
  key="default",
  label="Everywhere else",
  context="General visitor to the site; intent unknown. Ask what brought them in before assuming.",
  greeting_mode="generated",
  is_default=True,                    # at most one default per tenant; setting this unsets any other
)

一旦剧本运行了一段时间，page_context_stats() 会显示哪些被打开以及哪些建议问题被点击——以便您根据数据而非猜测来调整文案。

反馈。 向用户提供控制台链接以查看和编辑这些内容—— https://console.agent4.io/#/page-contexts ——并确认每个 url_pattern 的解析方式符合他们的预期（步骤 3）。静态站点无需更改代码即可使用聊天小部件；对于没有每个视图独立 URL 的单页应用，可以按其 key 命名剧本。

即时收集的开场白

如果剧本的 context 明确指示在初次接触时呈现表单——例如 "在您的开场白/问候语中呈现预订表单：(1) 首选渠道（电话/电子邮件——单选）， (2) 电话或电子邮件（文本）"——生成的开场白将包含该交互式表单，并且初始问题将被抑制（表单即为指引）。提交表单算作正常访客消息，因此 save_contact / schedule_followup 会像对话中途一样触发。

用于那些“先询问”就是全部目的的场景——“预订回调”、“留言”—— 并将字段数量保持在 2-3 个。对于访客希望先获取答案的场景（支持、故障排除），让对话正常开始，并在第一条回复中收集信息。

记录必须包含联系方式——这是设计使然

每个创建记录的工具（submit_lead、escalate、request_booking、open_checklist） 除非 contact.email 或 contact.phone 已填写，否则拒绝调用——无法跟进的记录是噪音，而非潜在客户。拒绝消息会告诉智能体该怎么做（先询问联系方式，切勿编造），因此让您的剧本在开场时收集电子邮件/电话——上述的开场白表单正是为此而设。

确定性地归档表单提交

对于收集类剧本（预订、潜在客户、投诉），在 context 中附加机器标记：[[inbox:submit_lead]]、[[inbox:escalate]] 或 [[inbox:request_booking]]。该剧本上的表单提交将在模型回复之前由平台归档——回复的引用保证是已归档记录的引用，并且联系方式会一并保存。保留文本说明：它们涵盖了自由对话路径（通过表单提供详细信息），其中模型仍会执行归档。