page-agent浏览器扩展SidePanel侧边栏UI源码解读：ConfigPanel与历史面板实现完全指南
【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent
page-agent是一个纯 JavaScript 实现的页面内 GUI agent，可以用自然语言控制 Web 界面。其 Chrome 扩展版的核心交互入口就是SidePanel 侧边栏面板：在这里输入任务、查看 Agent 执行过程、配置 LLM 参数、管理历史会话。本文将带你快速读懂侧边栏的源码结构，重点剖析 ConfigPanel 设置面板与历史面板的实现细节。
SidePanel 整体架构：一个状态机驱动的聊天界面
侧边栏入口是 App.tsx，整个面板只用一个view状态字段在 4 个视图之间切换：
type View = | { name: 'chat' } | { name: 'config' } | { name: 'history' } | { name: 'history-detail'; sessionId: string }没有引入路由库，用条件渲染替代传统页面跳转，非常符合扩展侧边栏"轻量单页"的场景 👍
关键设计点：
- 会话自动持久化：通过
useEffect监听status变化，当状态从running变为completed / error / stopped时自动调用saveSession()把本次任务写入 IndexedDB（见 App.tsx 第 34-50 行） - 自动滚动：新事件到来时把历史区滚动到底部，模拟"实时日志"体验
- 输入框交互：Enter 发送（Shift+Enter 换行），并处理了中文输入法合成期的误触发（
isComposing判断） - 聊天视图由头部（Logo + 状态点 + 历史/设置按钮）、中间事件流（
EventCard列表 +ActivityCard实时活动指示）、底部输入框三部分组成，运行中的任务按钮会变成红色的"停止"按钮
所有状态（status、history、activity、config等）来自 useAgent.ts 这个自定义 Hook——它内部创建MultiPageAgent实例，并通过监听statuschange、historychange、activity三类事件把 Agent 的状态同步到 React 状态中，是UI 层与 Agent 内核解耦的关键桥梁。
ConfigPanel 设置面板：LLM 配置与实验开关的实现
点击侧边栏右上角的齿轮图标进入 ConfigPanel.tsx，它是扩展的"设置中心"，负责管理所有 LLM 相关配置：
配置项一览
| 配置项 | 说明 | 类型 |
|---|---|---|
| Base URL | LLM API 地址，默认使用项目演示端点 | 文本 |
| Model | 模型名称（如gpt-5.1） | 文本 |
| API Key | 支持明文/掩码切换显示 | 密码 |
| Response Language | Agent 回复语言：跟随系统 / 英文 / 中文 | 下拉 |
| Max Steps | 最大执行步数（1-200），位于 Advanced 折叠区 | 数字 |
| System Instruction | 追加系统指令，定制 Agent 行为 | 多行文本 |
| 实验开关 | llms.txt 支持、包含所有标签页、禁用 named tool_choice | Switch |
值得学习的 3 个实现细节
外部配置变化的同步机制（ConfigPanel.tsx 第 52-64 行）：组件内用一个
prevConfig状态与传入的configprop 比对，发现不一致就重新同步所有本地 state。这让面板在"Agent 热更新配置"后仍能保持 UI 与数据源一致。User Auth Token 轮询读取（第 66-88 行）：面板每秒轮询
chrome.storage.local中的PageAgentExtUserAuthToken，读到后停止轮询。这个 Token 允许网页反向调用本扩展，是"网页驱动 Agent"玩法的凭证入口，界面提供一键复制。测试端点的合规提示：当
isTestingEndpoint(baseURL)为真时，会在表单中渲染一条琥珀色提示，告知用户正在使用免费测试 API 并链接到条款说明——开源项目合规意识的体现。
保存时handleSave调用onSave，实际执行的是useAgent中的configure()：把配置拆成llmConfig、language、advancedConfig三个键写入chrome.storage.local，再触发 React 状态更新，useAgent里的useEffect监听config变化从而重建 Agent 实例，整个链路是单向数据流。
历史面板：基于 IndexedDB 的会话持久化方案
历史功能的源码分三层：存储层 db.ts、列表层 HistoryList.tsx、详情层 HistoryDetail.tsx。
存储层：极简的 IndexedDB 封装
db.ts 用idb库封装了 4 个函数：saveSession/listSessions/getSession/deleteSession，外加一个clearSessions。数据结构非常清晰：
- 数据库名
page-agent-ext，单一 object storesessions - 每条记录
SessionRecord包含id（crypto.randomUUID()生成）、task任务文本、history（完整的事件数组）、status终态、createdAt时间戳 - 在
createdAt上建立by-created索引，listSessions通过索引倒序取出，实现"最新在前"
列表层：一个会"呼吸"的列表
HistoryList.tsx 的细节相当用心：
- 骨架屏加载态：加载时渲染 4 条
animate-pulse的占位条目 - 时间友好化：
timeAgo()把时间戳转成 "just now / 3m ago / 2h ago" 格式 - 悬停才出现的操作区：每条记录 hover 时才显示重跑（RotateCcw）、导出 JSON（调用 history-export.ts 下载）、删除三个小图标按钮，平时保持界面干净
- 状态用绿色对勾/红色叉号区分成功与否，条目本身支持键盘可访问（
role="button"+tabIndex）
详情层：只读回放 + 一键重跑
HistoryDetail.tsx 按sessionId取出单条记录，顶部显示任务与"Run again / Delete"操作，下方用与聊天视图相同的EventCard组件只读回放整段执行历史——组件复用让"实时执行"和"历史回放"共享同一套渲染逻辑，是很聪明的设计。
事件卡片：Agent 执行过程的可视化
实时流与历史详情共用的 cards.tsx 按事件类型渲染不同卡片：
- StepCard（蓝色左边框）：展示第 N 步的反思（评价/记忆/目标）、动作（点击/输入/滚动/跳转，各配专属图标）与原始请求/响应的可折叠调试区
- ObservationCard（绿色）：Agent 对页面结构的观察
- RetryCard（琥珀色）：自动重试提示，含当前/最大次数
- ErrorCard（红色）：错误信息 + 原始响应
- ResultCard：
done动作专属的绿色成功/红色失败结果卡 - ActivityCard：带脉冲光点的"Thinking... / Executing..."实时指示器
三层架构小结
整个侧边栏的数据流可以概括为一条清晰的单向链路：
ConfigPanel ──configure()──▶ chrome.storage.local ──▶ useAgent 重建 Agent Chat 输入 ──execute()──▶ MultiPageAgent ──事件──▶ cards.tsx 实时渲染 任务结束 ──saveSession()──▶ IndexedDB ──▶ HistoryList / HistoryDetail 回放- UI 状态（view 状态机）与 Agent 状态（status 事件）互不干扰
- 配置、会话、历史三类数据分别落在
chrome.storage.local和 IndexedDB，职责分明 - 组件高度复用：
EventCard同时服务于实时流与历史回放
这套 SidePanel 实现麻雀虽小五脏俱全，对于想给自己的浏览器扩展做一个"Agent 控制台"的同学来说，是非常值得参考的完整范本 📚
相关源码导航：
- 侧边栏入口：packages/extension/src/entrypoints/sidepanel/
- 设置面板：packages/extension/src/components/ConfigPanel.tsx
- 历史面板：packages/extension/src/components/HistoryList.tsx
- 存储封装：packages/extension/src/lib/db.ts
- 扩展 API 文档：docs/extension_api.md
【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
