InPage Agent 插件体系架构 (InPage Agent Plugin System Architecture) 是针对纯前端浏览器单页面应用（Single-Page Application, SPA）环境设计的可扩展智能体框架方案。它旨在解决大语言模型（Large Language Model, LLM）驱动的前端代理在脱离传统后端服务器时，如何实现即时能力扩展、动态工具注标（Dynamic Tool Registration）与长久持久化托管。

1. 核心设计哲学：执行环境的双轨解耦模型 (Dual-Track Decoupled Execution Model)

在浏览器端构建智能体系统时，执行 JavaScript 往往存在两种冲突的诉求：

  1. 即时性与纯粹性：只想快速运行一段无副作用的代码，或者 Agent 仅需读取浏览器当前环境的某些属性（例如时区、字体列表、屏幕像素比等）。
  2. 常驻性与侵入性：需要向系统长期注册新能力（如新的 Agent Tool、自定义 UI 按钮、持久化定时任务）。

若将两者混为一谈，会导致执行权限管理极其混乱，或者因为过度沙箱化导致无法访问宝贵的 Web 原生 API。因此，系统确立了严格的双轨模型 (Dual-Track Model)：

维度即时原生 JS 执行器 (Instant Native JS Runner)常驻插件体系 (Persistent Plugin System)
生命周期单次瞬时求值 (Stateless, Short-lived)随宿主启动常驻 (Stateful, Long-lived)
触发源用户点击工作台「运行」或 Agent 调用 run_js 工具系统初始化启动 (Boot) / 用户在插件面板启停
存储介质无需持久化（或仅作为虚拟文件系统普通的 .js 文件）localStorage 或虚拟文件系统固定目录持久化
能力边界执行代码、捕获控制台日志、返回结果注入 Agent 工具、拦截生命周期钩子 (Hooks)、注册 UI 按钮
上下文注入仅注入作用域代理 console注入完整的 PluginContext 实例

2. 插件生命周期与宿主加载流水线 (Lifecycle & Loading Pipeline)

常驻插件的生命周期包含五个核心阶段：

  1. 安装阶段 (Installation)：
    用户可通过粘贴代码清单、上传插件包或直接从工作区代码编辑器将当前代码「另存为插件」。
  2. 持久化阶段 (Persistence)：
    插件的元数据清单（Manifest）与执行体源码存储于浏览器的本地存储（LocalStorage）或 IndexedDB 中，确保浏览器刷新后不丢失。
  3. 引导启动阶段 (Boot & Instantiation)：
    当应用程序加载初始化时，插件管理器（Plugin Manager）扫描已启用的插件，并为每个插件创建一个独立的插件扩展上下文（Plugin Context）。
  4. 激活阶段 (Activation)：
    调用插件入口函数 activate(context)，插件通过上下文完成工具注标、钩子挂载与 UI 渲染。
  5. 停用与卸载阶段 (Deactivation & Teardown)：
    当插件被禁用或删除时，宿主自动撤销该插件注册过的所有 Agent 工具与事件监听器，避免内存泄露与脏状态残留。

3. 插件宿主上下文设计 (PluginContext API)

每个插件仅能通过宿主显式传递的上下文对象进行扩展，其主要接口能力包括：

  • 动态工具注标 (Dynamic Tool Registration)：
    允许插件声明 Agent 可调用的新工具，包含参数 JSON Schema 与异步执行函数。当 Agent 生成工具调用时，系统无缝分发给插件。

  • 生命周期钩子 (Lifecycle Hooks)：

    • beforeAgentTurn：在 Agent 开始生成回复前注入自定义上下文。
    • afterAgentTurn：在 Agent 生成回复后进行内容审查或数据归档。
    • beforeToolCall / afterToolCall：对特定工具调用前后进行拦截或参数篡改防护。
    • onFileChange：响应虚拟文件系统（Virtual File System, VFS）的文件变动。
  • UI 挂载点 (UI Action Registry)：
    允许在工作区顶部导航栏、侧边栏或代码编辑器工具栏注标自定义操作图标与下拉命令。
  • 隔离键值存储 (Scoped Storage)：
    为每个插件分配带命名空间前缀的本地持久化存储，互不干扰。

4. 浏览器端单用户实用主义与容错边界 (Pragmatism & Resilience Boundaries)

在纯前端单用户产品形态中，用户自身就是代码的编写者与运行者。传统云端多租户系统采用的强对抗重型沙箱（如限制 window、深度属性冻结、影子作用域 Shadow Realm）在前端单用户场景下往往带来巨大的交互阻力和 Web API 调用障碍。

本架构采取单用户实用主义 (Single-User Pragmatism) 与防御性容错边界 (Resilient Error Boundaries) 策略：

  1. 完整 Web API 开放：保留对 DOM、Canvas、Web Audio、Fetch、Intl 等原生能力的直接访问，赋予 Agent 与插件最大限度的浏览器交互能力。
  2. 执行故障隔离 (Failure Isolation)：
    插件在 try/catch 和未捕获 Promise 保护下执行。单个插件的内部抛错仅被记录为告警，绝不允许阻断主界面的渲染或 Agent 的正常思考。
  3. 超时看门狗 (Timeout Watchdog)：
    针对同步长任务与可能导致主线程假死的死循环，设置异步竞态超时上限（Timeout Guard），保障页面交互的持续可用。

本文归档于个人知识库 · 领域：CS & AI · 模块：04 Project_CS_AI/AI apps