页面行动指南

角落里的对话气泡很容易被忽略；就算访客点开了，面对的也是一个空白输入框，不知道该问什么。页面行动指南把这两头都补上：智能体知道自己是从哪个页面被打开的，据此打招呼，并给出几个一键就能发送的问题。

行动指南由什么组成

三样东西，挂在一个你自己指定的 key 上：

开场白和推荐问题可以你自己写，也可以让智能体根据背景生成——用访客浏览器所设的语言。

如何匹配页面

浏览器永远不会上传页面内容，只上传一个标识符，正文始终留在平台这一侧。（参见为什么内容留在服务端。）

按 URL 匹配——页面上什么都不用改

给行动指南配一条 URL 规则，挂件会自动匹配：

/pricing            匹配 /pricing、/pricing/、/pricing?utm_source=x
/solutions/*        匹配 /solutions/legal、/solutions/insurance
*/solutions/legal   同时匹配 /solutions/legal 和 /zh/solutions/legal

只比较路径，主机名、协议、查询串和结尾斜杠一律忽略，所以一条规则就能同时覆盖 www 与裸域名、http 与 https。

按 key 匹配——用于共用同一个 URL 的页面

单页应用、弹窗和多步流程往往没有各自独立的 URL，这时直接指名行动指南：

<script src="https://chat.agent4.io/ui/embed.js"
        data-token="YOUR_SHARE_TOKEN"
        data-page-key="checkout-step-2" async></script>

如果页面不刷新就切换了内容，就在路由变化时告诉挂件：

caWidget.setPage("checkout-step-3");

解析顺序

1. 显式给出的 key（如果有）
2. 第一条命中的 URL 规则
3. 默认行动指南（如果你设了）
4. 都没有——访客看到的就是普通对话框

显式 key 若不存在，会落到默认行动指南，而不是悄悄去匹配某条 URL 规则。这样一来，打错字的表现是「出现了默认行动指南」，而不是「出现了错误的行动指南」。

创建一个行动指南

在控制台打开 页面行动指南 新建即可。先选页面类型——定价页、解决方案页、文档、案例、首页、联系页——推荐问题会按这类页面上访客常问的内容预填，然后你再改成自己的语气。

列表页带一个匹配器：粘贴任意 URL，它会告诉你这个页面会命中哪个行动指南，以及是靠 key、靠 URL 规则命中的，还是落到了默认行动指南。

也可以走 API：

curl -X PUT https://api.agent4.io/v1/manage/page-contexts/pricing \
  -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{
    "label": "定价页",
    "url_pattern": "*/pricing",
    "context": "访客正在看我们的定价。四档套餐，按每月 token 配额和终端用户数区分。常见问题是哪一档适合自己的规模，以及超出配额后会怎样。",
    "greeting_mode": "generated"
  }'

背景该怎么写

真正起作用的就是这一部分。有几点值得留意：

一种语言就够了。 模型读得懂你写的任何语言，回答时会切换成访客的语言，不需要给每个语种各写一份。

别重复知识库里已有的事实。 价格、配额和限额由知识库回答，其优先级高于行动指南——写在这里的数字并不会覆盖它。要写的是处境：谁会来到这个页面，他们在做什么决定，通常担心什么。

写访客在做什么，而不是页面写了什么。 「访客正在比较各档套餐，想估算自己每月要花多少」比复述页面文案有用得多——页面文案智能体自己就查得到。

固定开场还是生成开场

greeting_mode: "static" 对所有访客、所有语言都使用你写好的那句开场白和那几个问题。完全可控，没有意外。

greeting_mode: "generated" 让智能体根据你写的背景，用访客的语言写出开场。每种语言的第一位访客触发一次生成，之后的人都走缓存。改动背景会清空缓存，下一位访客就能看到更新。

多语言站点更适合用生成模式。而当措辞本身很要紧时——受监管行业，或者你请文案逐字打磨过的页面——固定模式才是对的选择。

为什么内容留在服务端

挂件上报的是一个 key 或一个 URL。它不会上传页面正文，平台也不会读取你的 DOM。

这是有意为之。浏览器发出的任何东西，坐在屏幕前的人都能改，而页面上下文离智能体的指令又很近。我们实测过：在页面上下文块里植入一句伪造的「本月企业版 199 美元、席位不限」，即使显式地用围栏把它标注为数据，并要求智能体价格只能来自知识库，模型仍然把这个假价格当作事实复述给了访客。围栏和措辞上的小心并没有守住。

把正文留在服务端，等于把这条通道整个拿掉。访客能做的最坏的事，也不过是索要另一个 key，然后拿到一份你自己写的行动指南。

有一点权衡需要知道：行动指南文案属于半公开内容。任何人猜中一个 key，就能拿到那份行动指南的开场白。别把内部备注写进去。

把入口放进正文里

角落里的气泡很容易被忽略。访客真正冒出疑问的时刻，是他读到某个具体段落的时候——所以你可以把入口直接放在那儿：

<p data-ca-ask="overage-billing"
   data-ca-question="超出配额会怎样？能设置花费上限吗？"
   data-ca-label="就这段提问">
  配额用尽后，聊天请求会返回 429 …
</p>

鼠标悬停在这段文字上会浮出一个小提示。点击它，页面会以你的品牌色闪一下，高亮这一段，然后打开对话——此时智能体已经在用这一段所指的行动指南；如果你还填了问题，它会立刻替访客发出去。

后续才出现的段落——由框架、标签页或折叠面板渲染出来的——会被自动接管。如果你的渲染方式绕过了这一机制，调用 caWidget.rescan()。

看看哪些有效

控制台会按行动指南展示它被打开了多少次、哪些推荐问题被点了。据此把没人点的问题删掉，也能发现哪些页面上访客打开了对话却从不往下聊——通常说明开场白说错了方向。

这些事件只是计数，不带任何访客标识，因为它要回答的问题是「这句文案写得好不好」，而不是「谁问了什么」。