頁面劇本

角落的對話氣泡很容易被忽略，而點擊它的訪客會看到一個空白的方塊，不知道該問什麼。頁面劇本（Page playbooks）同時解決了這兩個問題：代理程式知道它是從哪個頁面開啟的，會相應地問候訪客，並提供幾個訪客可以一鍵發送的問題。

什麼是劇本

三個要素，綁定在你選擇的鍵（key）上：

開場白和問題可以由你撰寫，也可以由代理程式根據訪客瀏覽器的語言設定，從背景中生成。

匹配頁面

你從未從瀏覽器發送頁面內容——只發送識別碼。平台保留文字。（請參閱 為什麼內容保留在伺服器端。）

透過 URL — 無需更改頁面

為劇本提供 URL 規則，小工具會自動匹配：

/pricing            matches /pricing, /pricing/, /pricing?utm_source=x
/solutions/*        matches /solutions/legal, /solutions/insurance
*/solutions/legal   matches /solutions/legal AND /zh/solutions/legal

僅比較路徑——主機、協議、查詢字串和尾隨斜線都會被忽略，因此一條規則即可涵蓋 www 和裸域名、http 和 https。

透過鍵 — 用於共用 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. 明確的鍵（如果已提供）
2. 第一個匹配的 URL 規則
3. 預設劇本（如果有的話）
4. 無——訪客會看到普通的聊天方塊

不存在的明確鍵會回退到預設值，而不是靜默匹配某個 URL 規則。這樣，拼寫錯誤會顯示為「出現了預設值」，而不是「出現了錯誤的劇本」。

設定一個

在控制台中，開啟 Page playbooks 並建立一個。先選擇頁面類型——定價頁面、解決方案頁面、文件、案例研究、首頁、聯絡頁面——問題會預先填入訪客通常對該類頁面提出的問題。然後用你自己的語氣重寫它們。

列表檢視有一個匹配器：貼上任何 URL，它會告訴你該頁面將獲得哪個劇本，以及它是透過鍵、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": "Pricing page",
    "url_pattern": "*/pricing",
    "context": "The visitor is looking at our pricing. Four tiers separated by monthly token quota and end-user count. The usual questions are which tier fits their size and what happens when they go over.",
    "greeting_mode": "generated"
  }'

撰寫背景

這是真正發揮作用的部分。一些值得知道的事：

一種語言就夠了。 模型會讀取你寫的任何內容，並用訪客的語言回答。你不需要為每個區域設定提供翻譯。

不要重述知識庫中已有的事實。 價格、配額和限制是從知識庫中回答的，其權重高於劇本——這裡寫入的數字不會覆蓋它。請撰寫情境：誰會出現在這個頁面上，他們試圖做出什麼決定，他們通常擔心什麼。

撰寫訪客正在做的事情，而不是頁面所說的話。「訪客正在比較層級並試圖預測他們的月費」比頁面內容的摘要更有用——代理程式已經可以查閱頁面內容。

靜態或生成的開場白

greeting_mode: "static" 使用你為每個訪客、每種語言撰寫的確切開場白和問題。完全控制，沒有意外。

greeting_mode: "generated" 讓代理程式根據你的背景，用訪客的語言撰寫它們。每種語言的第一位訪客會觸發一次生成；之後的所有訪客都從快取中提供。編輯背景會清除快取，因此你的下一位訪客會看到更新。

對於多語言網站，生成是更好的預設值。當措辭至關重要時——受監管行業，或你已與文案人員調整過的頁面——靜態是正確的選擇。

生成的開場白可以攜帶表單。 當劇本背景明確表示要在初次聯絡時收集詳細資訊（「在問候中呈現表單」），開場白會帶有互動式表單——頻道、聯絡欄位，無論背景要求什麼——起始問題則退居其次。提交它是一條正常的訊息，因此代理程式的工具（save_contact、schedule_followup）會照常觸發。我們聯絡頁面的「與人類交談」卡片正是如此：在訪客輸入任何字詞之前，預訂表單就已顯示在螢幕上。

為什麼內容保留在伺服器端

小工具報告一個鍵或 URL。它從未上傳頁面文字，平台也從未讀取你的 DOM。

這是故意的。瀏覽器發送的任何內容都可以被坐在螢幕前的人編輯，而頁面上下文會接近代理程式的指令。我們進行了測試：在頁面上下文區塊中植入虛構的「本月企業版 199 美元，無限席位」——明確作為資料圍欄，並指示代理程式價格僅來自知識庫——模型將假價格作為事實重複給訪客。圍欄和仔細的措辭並未奏效。

將文字保留在伺服器上消除了整個管道。訪客能做的最壞事情是要求不同的鍵，並收到你自己撰寫的劇本。

值得知道的權衡：劇本文字是半公開的。任何猜測到鍵的人都會獲得該劇本的開場白。不要在裡面放置內部註解。

內容內部的入口點

角落的氣泡很容易被忽略。當某人實際上有一個問題時，正是他們正在閱讀特定段落的時候——因此你可以在那裡放置一個入口點：

<p data-ca-ask="overage-billing"
   data-ca-question="What happens if we go over, and can we cap the spend?"
   data-ca-label="Ask about this">
  When the quota is exhausted, chat requests return 429 …
</p>

懸停在段落上會顯示一個小提示。點擊它會以你的品牌顏色閃爍頁面，突出顯示該段落，然後開啟聊天，並已從該段落的劇本開始工作——如果你提供了一個，則立即詢問問題。

稍後添加的段落——由框架、標籤、手風琴添加——會自動被拾取。如果你以逃脫該機制的方式渲染內容，請呼叫 caWidget.rescan()。

連接你自己的按鈕

頁面上的任何元素都可以開啟所選劇本的對話——將現有的「聯絡銷售」或「預約示範」按鈕轉變為代理程式對話而非表單的模式：

const ok = caWidget.open("contact-sales");            // open on that playbook
caWidget.open("contact-sales", "I need a quote");     // …and ask the first question for them
if (!ok) location.href = "mailto:sales@example.com";  // false = script blocked; keep a fallback

無論你的網站使用哪種小工具形狀——角落氣泡或 Ask 命令列——caWidget.open 的工作方式相同。當小工具不可用時（腳本未載入或被阻止），它返回 false，因此點擊永遠不會成為死胡同：回退到按鈕之前的連結。

我們自己的 聯絡頁面 正是以此方式構建的——七個意圖卡片，每個卡片開啟一個劇本，該劇本詢問兩到三個問題，保存聯絡資訊，並預約後續跟進。

確定性收集歸檔

當劇本的職責是收集——預訂、潛在客戶、投訴——請在背景中添加機器標記：[[inbox:submit_lead]]、[[inbox:escalate]] 或 [[inbox:request_booking]]。當訪客在該劇本上提交互動式表單時，平台會在模型回應之前自行歸檔記錄——代理程式僅轉發工具返回的參考資訊。答案中的聯絡資訊以相同方式保存。

這存在是因為歸檔是唯一永遠不能依賴模型情緒的步驟：在生產測試中，一個帶有可用工具、已指示並被引導的中型模型仍會口頭確認——一次引用文件中的示例參考資訊，彷彿它是真實的。有了標記，回覆中的參考資訊每次都是你收件箱中的參考資訊。如果因任何原因歸檔失敗，對話會正常繼續，模型驅動的指示會接管。

查看哪些有效

控制台顯示每個劇本被開啟的次數，以及哪些起始問題被點擊。使用它來刪除沒人選擇的問題，並找出訪客開啟聊天但從未互動的頁面——這通常是開場白在談論錯誤事物的跡象。

事件僅為計數。它們不攜帶訪客識別碼，因為要回答的問題是「這份文案好不好」，而不是「誰問了什麼」。

他們說話之後

起始問題是為尚未說任何話的訪客準備的，一旦有人說了，它們就會退居其次。接下來發生的是單獨的開關： 後續建議，設定在代理程式上而非頁面上，在每次回覆後提供幾個一鍵問題。兩者共用訊息框上方的同一條帶，且從不衝突——一個破冰，另一個保持對話進行。