zoushiyang/page-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(website): add prompt caching guidance (#481)

Browse Source
This commit is contained in:
Simon
2026-04-27 20:14:01 +08:00
committed by GitHub
parent a7cc935453 cd035cd30f
commit 20f1b1f51e
4 changed files with 190 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
packages/website/src/components/Heading.tsx
View File

@@ -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' },
3: { tag: 'h3', className: 'text-xl font-semibold mb-3' },
2: { tag: 'h2', className: 'text-3xl font-semibold mb-4' },
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) {

29
packages/website/src/index.css
View File

@@ -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 也用中等字重 */

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

@@ -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
? '在请求发送前转换最终 request body。可用于处理供应商特定的缓存提示或私有参数。'
: 'Transform the final request body before sending it. Useful for provider-specific cache hints or private request parameters.',
description: isZh ? (
<>
在请求发送前转换最终 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'}

175
packages/website/src/pages/docs/features/models/page.tsx
View File

@@ -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，实现离线或局域网部署。'