docs(website): add prompt caching guidance

packages/website/src/components/Heading.tsx

@@ -2,7 +2,7 @@ import { ComponentPropsWithoutRef, useEffect, useRef } from 'react'
 
 import { cn } from '@/lib/utils'
 
-type Level = 2 | 3
+type Level = 2 | 3 | 4
 
 interface HeadingProps extends Omit<ComponentPropsWithoutRef<'h2'>, 'children'> {
 	id: string
@@ -11,8 +11,9 @@ interface HeadingProps extends Omit<ComponentPropsWithoutRef<'h2'>, 'children'>
 }
 
 const levelStyles = {
-	2: { tag: 'h2', className: 'text-2xl font-semibold mb-4' },
+	2: { tag: 'h2', className: 'text-3xl font-semibold mb-4' },
-	3: { tag: 'h3', className: 'text-xl font-semibold mb-3' },
+	3: { tag: 'h3', className: 'text-[1.375rem] font-semibold mb-3' },
+	4: { tag: 'h4', className: 'text-[1.0625rem] font-medium mb-2' },
 } as const
 
 export function Heading({ id, level = 2, className, children, ...props }: HeadingProps) {

packages/website/src/index.css

@@ -95,7 +95,7 @@ body {
 	line-height: 1.6;
 }
 
-/* 标题使用中等字重（相对细体更重，但比默认 bold 更轻） */
+/* 文档标题层级需要比正文标题更清晰，避免 h2/h3/h4 视觉差异过小。 */
 .prose h1,
 .prose h2,
 .prose h3,
@@ -103,6 +103,33 @@ body {
 .prose h5,
 .prose h6 {
 	font-weight: 480;
+	line-height: 1.25;
+	letter-spacing: -0.015em;
+}
+
+.prose h2[id] {
+	margin-bottom: 1rem;
+	padding-bottom: 0.45rem;
+	border-bottom: 1px solid rgba(23, 23, 23, 0.12);
+	font-size: 1.875rem;
+	font-weight: 650;
+}
+
+.prose h3[id] {
+	margin-bottom: 0.75rem;
+	font-size: 1.375rem;
+	font-weight: 600;
+}
+
+.prose h4[id] {
+	margin-bottom: 0.5rem;
+	font-size: 1.0625rem;
+	font-weight: 560;
+	letter-spacing: -0.005em;
+}
+
+.dark .prose h2[id] {
+	border-bottom-color: rgba(255, 255, 255, 0.14);
 }
 
 /* strong/b 也用中等字重 */

packages/website/src/pages/docs/advanced/page-agent-core/page.tsx

@@ -159,9 +159,30 @@ const result = await agent.execute('Fill in the form with test data')`}
 						{
 							name: 'transformRequestBody',
 							type: '(requestBody) => Record<string, unknown> | undefined',
-							description: isZh
+							description: isZh ? (
-								? '在请求发送前转换最终 request body。可用于处理供应商特定的缓存提示或私有参数。'
+								<>
-								: 'Transform the final request body before sending it. Useful for provider-specific cache hints or private request parameters.',
+									在请求发送前转换最终 request body。可用于处理供应商特定的缓存提示或私有参数。查看{' '}
+									<Link
+										href="/features/models#prompt-caching"
+										className="text-blue-600 dark:text-blue-400 hover:underline"
+									>
+										主动缓存示例
+									</Link>
+									。
+								</>
+							) : (
+								<>
+									Transform the final request body before sending it. Useful for provider-specific
+									cache hints or private request parameters. See{' '}
+									<Link
+										href="/features/models#prompt-caching"
+										className="text-blue-600 dark:text-blue-400 hover:underline"
+									>
+										prompt caching examples
+									</Link>
+									.
+								</>
+							),
 						},
 						{
 							name: 'disableNamedToolChoice',
@@ -181,42 +202,6 @@ const result = await agent.execute('Fill in the form with test data')`}
 					]}
 				/>
 
-				<h3 className="text-lg font-semibold mt-6 mb-3 text-gray-800 dark:text-gray-200">
-					{isZh ? 'transformRequestBody 示例' : 'transformRequestBody Example'}
-				</h3>
-				<p className="text-gray-600 dark:text-gray-400 mb-4">
-					{isZh
-						? '如果某个供应商需要私有字段或缓存提示，可以通过 transformRequestBody 在发送前透传请求体，而不需要把供应商逻辑写进 PageAgent 内部。'
-						: 'If a provider needs private fields or cache hints, use transformRequestBody to tweak the request body before sending it instead of baking provider-specific logic into PageAgent.'}
-				</p>
-				<CodeEditor
-					language="typescript"
-					code={`const agent = new PageAgentCore({
-  pageController: new PageController({ enableMask: true }),
-  baseURL: 'https://your-provider.example/v1',
-  apiKey: 'your-api-key',
-  model: 'qwen3.5-plus',
-  transformRequestBody: (requestBody) => {
-    const messages = requestBody.messages
-    if (!Array.isArray(messages)) return
-
-    const systemMessage = messages.find(
-      (message) => message && typeof message === 'object' && message.role === 'system'
-    ) as { role: string; content?: unknown } | undefined
-
-    if (!systemMessage || typeof systemMessage.content !== 'string') return
-
-    systemMessage.content = [
-      {
-        type: 'text',
-        text: systemMessage.content,
-        cache_control: { type: 'ephemeral' },
-      },
-    ]
-  },
-})`}
-				/>
-
 				{/* Agent Config */}
 				<h3 className="text-lg font-semibold mt-6 mb-3 text-gray-800 dark:text-gray-200">
 					{isZh ? 'Agent 配置' : 'Agent Config'}

packages/website/src/pages/docs/features/models/page.tsx

@@ -1,4 +1,5 @@
 import { Fragment } from 'react'
+import { Link } from 'wouter'
 
 import CodeEditor from '@/components/CodeEditor'
 import { Heading } from '@/components/Heading'
@@ -126,46 +127,6 @@ const pageAgent = new PageAgent({
 				/>
 			</section>
 
-			<section className="mb-10">
-				<Heading id="production-authentication" className="text-2xl font-semibold mb-4">
-					{isZh ? '🔐 生产环境鉴权' : '🔐 Production Authentication'}
-				</Heading>
-				<p className="text-sm text-gray-600 dark:text-gray-400 mb-3">
-					{isZh
-						? '如果你只是将它用作个人助手，可以直接连接你的 LLM 服务。'
-						: 'If you only use it as a personal assistant, you can connect to your LLM service directly.'}
-				</p>
-				<p className="text-sm text-gray-600 dark:text-gray-400 mb-3">
-					{isZh ? (
-						<>
-							如果你计划将它集成到你的 Web 应用中，建议搭建一个后端代理来转发 LLM 请求，并使用{' '}
-							<code>customFetch</code> 携带 Cookie 或其他鉴权信息：
-						</>
-					) : (
-						<>
-							If you plan to integrate it into your web app, it's better to have a backend proxy for
-							the LLM and use <code>customFetch</code> to authenticate the request with cookies or
-							other methods:
-						</>
-					)}
-				</p>
-				<CodeEditor
-					code={`const agent = new PageAgent({
-  baseURL: '/api/llm-proxy',
-  model: 'gpt-5.1',
-  customFetch: (url, init) =>
-    fetch(url, { ...init, credentials: 'include' }),
-});`}
-				/>
-				<div className="mt-4 bg-yellow-50 dark:bg-yellow-950/20 border-l-4 border-yellow-500 p-4 rounded-r-lg">
-					<p className="text-sm font-semibold text-yellow-900 dark:text-yellow-200">
-						{isZh
-							? '⚠️ 永远不要把真实的 LLM API Key 提交到前端代码中'
-							: '⚠️ NEVER commit real LLM API keys to your frontend code'}
-					</p>
-				</div>
-			</section>
-
 			<section className="mb-10">
 				<Heading id="free-testing-api">{isZh ? '免费测试接口' : 'Free Testing API'}</Heading>
 				<p className="text-sm text-gray-600 dark:text-gray-400 mb-4">
@@ -215,7 +176,139 @@ LLM_MODEL_NAME="qwen3.5-plus"`}
 			</section>
 
 			<section className="mb-10">
-				<Heading id="local-runtimes">{isZh ? '本地运行时' : 'Local Runtimes'}</Heading>
+				<Heading id="production-authentication" className="text-2xl font-semibold mb-4">
+					{isZh ? '🔐 生产环境鉴权' : '🔐 Production Authentication'}
+				</Heading>
+				<p className="text-sm text-gray-600 dark:text-gray-400 mb-3">
+					{isZh
+						? '如果你只是将它用作个人助手，可以直接连接你的 LLM 服务。'
+						: 'If you only use it as a personal assistant, you can connect to your LLM service directly.'}
+				</p>
+				<p className="text-sm text-gray-600 dark:text-gray-400 mb-3">
+					{isZh ? (
+						<>
+							如果你计划将它集成到你的 Web 应用中，建议搭建一个后端代理来转发 LLM 请求，并使用{' '}
+							<code>customFetch</code> 携带 Cookie 或其他鉴权信息：
+						</>
+					) : (
+						<>
+							If you plan to integrate it into your web app, it's better to have a backend proxy for
+							the LLM and use <code>customFetch</code> to authenticate the request with cookies or
+							other methods:
+						</>
+					)}
+				</p>
+				<CodeEditor
+					code={`const agent = new PageAgent({
+  baseURL: '/api/llm-proxy',
+  model: 'gpt-5.1',
+  customFetch: (url, init) =>
+    fetch(url, { ...init, credentials: 'include' }),
+});`}
+				/>
+				<div className="mt-4 bg-yellow-50 dark:bg-yellow-950/20 border-l-4 border-yellow-500 p-4 rounded-r-lg">
+					<p className="text-sm font-semibold text-yellow-900 dark:text-yellow-200">
+						{isZh
+							? '⚠️ 永远不要把真实的 LLM API Key 提交到前端代码中'
+							: '⚠️ NEVER commit real LLM API keys to your frontend code'}
+					</p>
+				</div>
+			</section>
+
+			<section className="mb-10">
+				<Heading id="prompt-caching">{isZh ? '主动缓存' : 'Prompt Caching'}</Heading>
+				<p className="text-sm text-gray-600 dark:text-gray-400 mb-4">
+					{isZh ? (
+						<>
+							一些 LLM 能从主动缓存中受益很多。由于各个供应商的主动缓存接口不同，推荐使用{' '}
+							<Link
+								href="/advanced/page-agent-core#configuration"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								transformRequestBody
+							</Link>{' '}
+							为你的模型供应商配置缓存提示。
+						</>
+					) : (
+						<>
+							Some LLMs benefit significantly from prompt caching. Because each provider exposes
+							caching differently, use{' '}
+							<Link
+								href="/advanced/page-agent-core#configuration"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								transformRequestBody
+							</Link>{' '}
+							to add provider-specific cache hints.
+						</>
+					)}
+				</p>
+
+				<div className="space-y-6">
+					<section>
+						<Heading id="prompt-caching-claude" level={3}>
+							Claude
+						</Heading>
+						<p className="text-sm text-gray-600 dark:text-gray-400 mb-4">
+							{isZh
+								? 'Claude 支持全局 Automatic prompt caching。使用兼容 Claude 的代理时，只需要在请求体顶层添加 cache_control。'
+								: 'Claude supports global Automatic prompt caching. When using a Claude-compatible proxy, add cache_control at the top level of the request body.'}
+						</p>
+						<CodeEditor
+							language="typescript"
+							code={`const pageAgent = new PageAgent({
+  baseURL: 'https://your-claude-proxy.example/v1',
+  apiKey: 'your-api-key',
+  model: 'claude-sonnet-4.5',
+  transformRequestBody: (requestBody) => ({
+    ...requestBody,
+    cache_control: { type: 'ephemeral' },
+  }),
+});`}
+						/>
+					</section>
+					<section>
+						<Heading id="prompt-caching-qwen" level={3}>
+							{isZh ? '阿里云百炼 Qwen' : 'Alibaba Cloud Bailian Qwen'}
+						</Heading>
+						<CodeEditor
+							language="typescript"
+							code={`const pageAgent = new PageAgent({
+  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+  apiKey: 'your-api-key',
+  model: 'qwen3.5-plus',
+  transformRequestBody: (requestBody) => {
+    const [systemMessage, ...restMessages] = requestBody.messages
+
+    if (systemMessage.role !== 'system' || typeof systemMessage.content !== 'string') {
+      return requestBody
+    }
+
+    return {
+      ...requestBody,
+      messages: [
+        {
+          ...systemMessage,
+          content: [
+            {
+              type: 'text',
+              text: systemMessage.content,
+              cache_control: { type: 'ephemeral' },
+            },
+          ],
+        },
+        ...restMessages,
+      ],
+    }
+  },
+});`}
+						/>
+					</section>
+				</div>
+			</section>
+
+			<section className="mb-10">
+				<Heading id="local-runtimes">{isZh ? '本地 LLMs' : 'Local LLMs'}</Heading>
 				<p className="text-sm text-gray-600 dark:text-gray-400 mb-6">
 					{isZh
 						? '通过 Ollama、LM Studio 等本地 OpenAI-compatible 运行时接入 PageAgent，实现离线或局域网部署。'