页面上下文支持（Page Context）¶

概述¶

RAG 小部件（widget.js）现在默认会自动提取当前页面的主要内容并随聊天请求发送到后端 /chat 接口。该功能帮助聊天机器人更好地理解用户当前正在查看的页面，从而在需要时能提供更精确的页面摘要或上下文相关回答。

功能要点¶

默认启用：小部件会提取页面的标题、URL 与正文文本，并在请求体中包含 pageContext 字段。
触发条件：当用户询问"总结该页面"、"这篇文章讲了什么"或使用代词引用当前页面时，后端会优先使用 pageContext 来回答。
截断控制：为了避免超出 token 限制，页面文本会截断为最多 3000 字符（客户端限制）。
私密性：页面上下文只会随聊天请求发送到 RAG Worker，遵循现有的隐私与日志策略；请注意避免发送敏感信息。

请求格式示例¶

聊天请求（示例）：

{
  "message": "请帮我总结这篇文章的主要观点",
  "history": [],
  "language": "zh",
  "pageContext": {
    "title": "Kubernetes 入门指南",
    "url": "https://jimmysong.io/blog/kubernetes-intro/",
    "content": "Kubernetes 是一个开源的容器编排平台..."
  }
}

前端集成说明¶

将小部件嵌入页面的方法保持不变：

<script src="https://website-rag-worker.jimmysong.io/widget.js" data-endpoint="https://website-rag-worker.jimmysong.io" defer></script>
<div id="ai-chatbot"></div>

默认情况下，小部件会自动检测并包含页面上下文。如果你希望禁用页面上下文采集，可以在 script 标签中使用 data-include-page-context="false"：

<script src="https://website-rag-worker.jimmysong.io/widget.js" data-endpoint="https://website-rag-worker.jimmysong.io" data-include-page-context="false" defer></script>

后端处理行为¶

Worker 接收到请求后，会将 pageContext 合并到 LLM prompt 中，并在 prompt 中添加明确的优先指引：当用户要求总结该页面或提到当前页面时，优先使用 pageContext 的内容。
pageContext 不会替代知识库检索结果，而是与检索到的上下文（contexts）共同用于生成回答。
在日志中会记录 hasPageContext、pageTitle 和 pageUrl 以便于调试与监控。

使用建议与隐私提示¶

推荐用于博客文章、文档、教程类页面的即时摘要与内容确认
对于包含敏感信息的页面，建议禁用页面上下文采集或在服务器端进行屏蔽/脱敏处理

本地测试建议¶

在本地插件环境中启动页面（make server），打开任何一篇文章页面
打开 DevTools → Network，并在 Console 中观察 Worker 的 /chat 请求
点击小部件的 "总结该页面" FAQ，或在小部件输入框中输入类似“总结该页面”的自然语言请求
确认 /chat 请求体中包含 pageContext 字段，并且 pageContext.content 包含该页面的正文（经过清理和截断）

示例 curl 测试（模拟带 pageContext 的请求）：

curl -X POST 'https://website-rag-worker.jimmysong.io/chat' -H 'Content-Type: application/json' -d '{"message":"总结该页面","language":"zh","pageContext":{"title":"测试文章","url":"https://example.com/article","content":"文章主要内容的片段..."}}'

常见问题¶

Q: 页面上下文是否会被缓存？
A: 页面文本不会被单独缓存到外部数据库，它只是作为请求 payload 发给 Worker，用于生成实时回答。
Q: 我可以完全控制采集策略吗？
A: 当前小部件提供 data-include-page-context 开关以启用/禁用采集。未来版本可能提供更精细的控制选项（例如仅提取标题或限制长度）。

End of Document