refactor: monorepo

2025-12-01 20:11:12 +08:00
parent 1b9970da14
commit adec9d8197
98 changed files with 1144 additions and 1129 deletions
@@ -0,0 +1,66 @@
+import BetaNotice from '@/components/BetaNotice'
+import CodeEditor from '@/components/CodeEditor'
+
+export default function BestPractices() {
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">最佳实践</h1>
+
+			<BetaNotice />
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-6 leading-relaxed">
+				使用 page-agent 的最佳实践和常见问题解决方案。
+			</p>
+
+			<h2 className="text-2xl font-bold mb-3">性能优化</h2>
+
+			<div className="space-y-4 mb-6">
+				<div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-green-900 dark:text-green-300">
+						⚡ 减少 API 调用
+					</h3>
+					<p className="text-gray-600 dark:text-gray-300 mb-3">
+						合并多个操作指令，减少与 AI 模型的交互次数。
+					</p>
+
+					<CodeEditor
+						code={`// 推荐：合并操作
+await pageAgent.execute('填写表单：姓名张三，邮箱test@example.com，然后提交');
+
+// 不推荐：分别操作
+await pageAgent.execute('填写姓名张三');
+await pageAgent.execute('填写邮箱test@example.com');
+await pageAgent.execute('点击提交按钮');`}
+					/>
+				</div>
+
+				<div className="p-4 bg-blue-50 dark:bg-blue-900/20 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-blue-900 dark:text-blue-300">
+						🎯 精确的元素描述
+					</h3>
+					<p className="text-gray-600 dark:text-gray-300">
+						使用具体、明确的元素描述，提高操作成功率。
+					</p>
+				</div>
+			</div>
+
+			<h2 className="text-2xl font-bold mb-3">安全建议</h2>
+
+			<div className="space-y-3 mb-6">
+				<div className="p-3 bg-red-50 dark:bg-red-900/20 rounded-lg border-l-4 border-red-500">
+					<h3 className="font-semibold mb-1 text-red-900 dark:text-red-300">重要操作保护</h3>
+					<p className="text-gray-600 dark:text-gray-300">对删除、支付等敏感操作设置黑名单保护。</p>
+				</div>
+
+				<div className="p-3 bg-yellow-50 dark:bg-yellow-900/20 rounded-lg border-l-4 border-yellow-500">
+					<h3 className="font-semibold mb-1 text-yellow-900 dark:text-yellow-300">数据脱敏</h3>
+					<p className="text-gray-600 dark:text-gray-300">启用数据脱敏功能，保护用户隐私信息。</p>
+				</div>
+			</div>
+
+			<h2 className="text-2xl font-bold mb-3">调试技巧</h2>
+
+			<CodeEditor code={`// TODO`} />
+		</div>
+	)
+}
@@ -0,0 +1,38 @@
+import BetaNotice from '@/components/BetaNotice'
+import CodeEditor from '@/components/CodeEditor'
+
+export default function CdnSetup() {
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">CDN 引入</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-6 leading-relaxed">
+				通过 CDN 快速集成 page-agent，无需复杂的构建配置。
+			</p>
+
+			<h2 className="text-2xl font-bold mb-3">快速开始</h2>
+
+			<CodeEditor
+				className="mb-8"
+				code={`
+// 仅供测试使用，稳定 CDN 待定
+<script src="https://hwcxiuzfylggtcktqgij.supabase.co/storage/v1/object/public/demo-public/v0.0.4/page-agent.js" crossorigin="true" type="text/javascript"></script>
+
+<script>
+	window.pageAgent.panel.show()
+</script>`}
+			/>
+
+			<div className="bg-yellow-50 dark:bg-yellow-900/20 p-4 rounded-lg">
+				<h3 className="text-lg font-semibold mb-2 text-yellow-900 dark:text-yellow-300">
+					⚠️ 注意事项
+				</h3>
+				<ul className="text-gray-600 dark:text-gray-300 space-y-1">
+					<li>• 生产环境建议使用固定版本号</li>
+					<li>• 确保 HTTPS 环境下使用</li>
+					<li>• 配置 CSP 策略允许脚本执行</li>
+				</ul>
+			</div>
+		</div>
+	)
+}
@@ -0,0 +1,108 @@
+import CodeEditor from '@/components/CodeEditor'
+
+export default function Configuration() {
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">配置选项</h1>
+
+			<CodeEditor
+				className="mb-8"
+				language="typescript"
+				code={`// config
+type PageAgentConfig = LLMConfig & AgentConfig & DomConfig
+
+interface LLMConfig {
+	baseURL?: string
+	apiKey?: string
+	model?: string
+	temperature?: number
+	maxTokens?: number
+	maxRetries?: number
+}
+
+interface AgentConfig {
+	language?: "en-US" | "zh-CN"
+
+	/**
+	 * Custom tools to extend PageAgent capabilities
+	 * @experimental
+	 * @note You can also override or remove internal tools by using the same name.
+	 * @see [tools](../tools/index.ts)
+	 *
+	 * @example
+	 * // override internal tool
+	 * import { tool } from 'page-agent'
+	 * const customTools = {
+	 * ask_user: tool({
+	 * 	description:
+	 * 		'Ask the user or parent model a question and wait for their answer. Use this if you need more information or clarification.',
+	 * 	inputSchema: zod.object({
+	 * 		question: zod.string(),
+	 * 	}),
+	 * 	execute: async function (this: PageAgent, input) {
+	 * 		const answer = await do_some_thing(input.question)
+	 * 		return "✅ Received user answer: " + answer
+	 * 	},
+	 * })
+	 * }
+	 *
+	 * @example
+	 * // remove internal tool
+	 * const customTools = {
+	 * 	ask_user: null // never ask user questions
+	 * }
+	 */
+	customTools?: Record<string, PageAgentTool | null>
+
+	// lifecycle hooks
+	// @todo: use event instead of hooks
+
+	onBeforeStep?: (this: PageAgent, stepCnt: number) => Promise<void> | void
+	onAfterStep?: (this: PageAgent, stepCnt: number, history: AgentHistory[]) => Promise<void> | void
+	onBeforeTask?: (this: PageAgent) => Promise<void> | void
+	onAfterTask?: (this: PageAgent, result: ExecutionResult) => Promise<void> | void
+
+	/**
+	 * @note this hook can block the disposal process
+	 * @note when dispose caused by page unload, "reason" will be 'PAGE_UNLOADING'. this method CANNOT block unloading. async operations may be cut.
+	 */
+	onDispose?: (this: PageAgent, reason?: string) => void
+
+	// page behavior hooks
+
+	/**
+	 * @experimental
+	 * Enable the experimental script execution tool that allows executing generated JavaScript code on the page.
+	 * @note Can cause unpredictable side effects.
+	 * @note May bypass some safe guards and data-masking mechanisms.
+	 */
+	experimentalScriptExecutionTool?: boolean
+
+	/**
+	 * TODO: @unimplemented
+	 * hook when action causes a new page to be opened
+	 * @note PageAgent will try to detect new pages and decide if it's caused by an action. But not very reliable.
+	 */
+	onNewPageOpen?: (this: PageAgent, url: string) => Promise<void> | void
+
+	/**
+	 * TODO: @unimplemented
+	 * try to navigate to a new page instead of opening a new tab/window.
+	 * @note will unload the current page when a action tries to open a new page. so that things keep in the same tab/window.
+	 */
+	experimentalPreventNewPage?: boolean
+}
+
+interface DomConfig {
+	interactiveBlacklist?: (Element | (() => Element))[]
+	interactiveWhitelist?: (Element | (() => Element))[]
+	include_attributes?: string[]
+	highlightOpacity?: number
+	highlightLabelOpacity?: number
+}
+
+`}
+			/>
+		</div>
+	)
+}
@@ -0,0 +1,115 @@
+import CodeEditor from '@/components/CodeEditor'
+
+export default function ThirdPartyAgentPage() {
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">接入第三方 Agent</h1>
+			<p className="mb-6 leading-relaxed text-gray-600 dark:text-gray-300">
+				将 pageAgent 作为工具接入你的答疑助手或 Agent 系统，成为你 Agent 的眼和手。
+			</p>
+
+			<div className="bg-blue-50 dark:bg-blue-900/20 rounded-lg p-4 mb-6">
+				<h3 className="text-lg font-semibold mb-2 text-blue-900 dark:text-blue-300">💡 核心价值</h3>
+				<p className="text-blue-800 dark:text-blue-200">
+					让你的答疑机器人不再只是"嘴巴"，而是拥有"眼睛"和"手"的完整智能体。
+				</p>
+			</div>
+
+			<h2 className="text-2xl font-bold mb-4">集成方式</h2>
+
+			<div className="space-y-4 mb-6">
+				<div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-green-900 dark:text-green-300">
+						1. Function Calling
+					</h3>
+					<CodeEditor
+						code={`// 定义工具
+const pageAgentTool = {
+  name: "page_agent",
+  description: "执行网页操作",
+  parameters: {
+    type: "object",
+    properties: {
+      instruction: { type: "string", description: "操作指令" }
+    },
+    required: ["instruction"]
+  },
+  execute: async (params) => {
+    const result = await pageAgent.execute(params.instruction)
+    return { success: result.success, message: result.message }
+  }
+}
+
+// 注册到你的 agent 中`}
+						language="javascript"
+					/>
+				</div>
+			</div>
+
+			<h2 className="text-2xl font-bold mb-4">应用场景</h2>
+			<div className="grid md:grid-cols-2 gap-4 mb-6">
+				<div className="bg-linear-to-br from-blue-50 to-purple-50 dark:from-gray-800 dark:to-gray-700 p-4 rounded-lg">
+					<h4 className="font-semibold mb-2 text-gray-900 dark:text-white">🤖 智能客服系统</h4>
+					<p className="text-sm text-gray-600 dark:text-gray-300">
+						客服机器人帮用户直接操作系统，如"帮我提交工单"
+					</p>
+				</div>
+				<div className="bg-linear-to-br from-green-50 to-blue-50 dark:from-gray-800 dark:to-gray-700 p-4 rounded-lg">
+					<h4 className="font-semibold mb-2 text-gray-900 dark:text-white">📋 业务流程助手</h4>
+					<p className="text-sm text-gray-600 dark:text-gray-300">
+						引导新员工完成复杂流程，如"完成客户入职"
+					</p>
+				</div>
+				<div className="bg-linear-to-br from-purple-50 to-pink-50 dark:from-gray-800 dark:to-gray-700 p-4 rounded-lg">
+					<h4 className="font-semibold mb-2 text-gray-900 dark:text-white">🎯 个人效率助手</h4>
+					<p className="text-sm text-gray-600 dark:text-gray-300">
+						跨网站帮你完成任务，如"预订会议室"
+					</p>
+				</div>
+				<div className="bg-linear-to-br from-orange-50 to-red-50 dark:from-gray-800 dark:to-gray-700 p-4 rounded-lg">
+					<h4 className="font-semibold mb-2 text-gray-900 dark:text-white">🔧 运维自动化</h4>
+					<p className="text-sm text-gray-600 dark:text-gray-300">
+						通过自然语言操作管理后台，如"重启服务器"
+					</p>
+				</div>
+			</div>
+
+			<h2 className="text-2xl font-bold mb-4">最佳实践</h2>
+			<div className="space-y-4 mb-6">
+				<div className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-gray-900 dark:text-white">错误处理</h3>
+					<CodeEditor code={`// @TODO`} language="javascript" />
+				</div>
+
+				<div className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-gray-900 dark:text-white">权限控制</h3>
+					<CodeEditor code={`// @TODO`} language="javascript" />
+				</div>
+			</div>
+
+			<div className="bg-yellow-50 dark:bg-yellow-900/20 border border-yellow-200 dark:border-yellow-800 rounded-lg p-4 mb-6">
+				<h3 className="text-lg font-semibold text-yellow-900 dark:text-yellow-100 mb-2">
+					⚠️ 注意事项
+				</h3>
+				<ul className="text-yellow-800 dark:text-yellow-200 space-y-1 text-sm">
+					<li>• 确保目标网站允许自动化操作</li>
+					<li>• 实现适当的频率限制</li>
+					<li>• 敏感操作建议要求人工确认</li>
+				</ul>
+			</div>
+
+			<div className="bg-linear-to-r from-green-50 to-blue-50 dark:from-green-900/20 dark:to-blue-900/20 p-4 rounded-lg">
+				<h3 className="text-lg font-semibold mb-2 text-gray-900 dark:text-white">🎉 开始集成</h3>
+				<p className="mb-3 text-gray-700 dark:text-gray-300">
+					通过这种方式，你的 Agent 系统就能真正成为用户的智能助手。
+				</p>
+				<a
+					href="/docs/integration/configuration"
+					className="inline-flex items-center px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition-colors duration-200"
+				>
+					查看配置选项 →
+				</a>
+			</div>
+		</div>
+	)
+}