核心概念

应用（Bundle）

一个应用 = 入口文件 + 可选的其它源码文件/资源 + 元信息。系统内部称为 bundle。应用有生命周期：开发中 → 提交审核 → 已上架 → 被安装。应用管理页的顶部 Tab 就对应这些阶段。

入口文件与元信息头

每个应用有一个入口文件（如 main.js / main.ts），顶部用 // ==UserScript== 注释块声明元信息：应用叫什么（@name）、在哪些页面运行（@match）、用哪些内置库（@require）。完整指令列表见「元信息头与指令」。

• 入口文件必须是 .js / .mjs / .ts / .tsx / .jsx；.vue 只能被 import，不能作入口
• 插件构建只认入口文件的指令。非入口文件头部的 // @require 只在终端直接 run <该文件> 时生效，编辑器会在这类行上给出 Warning，其它文件也不能借用它
• 从本地导入时，默认选文件名为 main / index / entry 的脚本作入口（与文件里有没有元信息头无关），找不到时取第一个脚本；可在导入对话框里改选，导入后也可在 IDE 的入口下拉框或终端 entryFile set <路径> 切换
• 切换入口后，应用名称、匹配范围、内置库全部改由新入口的头部决定：新入口没有元信息头时，下次编译会按 <all_urls> 注册且不启用任何内置库。删除入口文件时会自动改选当前打开的脚本或第一个脚本作入口。两种情况都要点「编译」后才会更新已注册的产物
• npm 依赖版本只读工作区根目录的 package.json，与入口文件放在哪个目录无关

应用名称与 @name

项目名与入口文件的 @name 双向同步：修改 @name 并保存即把项目重命名为新名字；在应用列表里改名（或 AI 按首条对话自动起名）后，入口文件的 @name 会被改写成新项目名。删掉 @name 不会清空项目名，编译时仍沿用项目名。

两种源码形态

所有应用（包括纯 JS 应用）都由浏览器内编译器打包成单文件产物后注入页面。下表只是导入时展示的分类，不影响编译流程与指令语义：

形态	判定条件	编译
JS 源码应用	入口是单个 .js，无 ESM import	浏览器内编译打包后注入
源码工程应用	包含 .vue / .ts / .tsx / .jsx / .mjs 或 ESM import	浏览器内编译打包后注入

两种形态共用同一套元信息头。本地模块与 npm 包都用标准 import 引用，@require 只用来声明内置运行时库（写本地文件会编译失败）。

内置库

扩展运行时直接提供 8 个库，不占应用体积，用 @require <id> 启用（LFRuntime 除外，它始终可用）：

库	全局变量	一句话用途
runtime	LFRuntime	应用上下文：元信息、热重载、资源、样式注入（始终可用）
dom	LFDOM	DOM 操作、注入挂载、定位器、语义快照
store	LFStore	跨站点共享的应用级键值存储
http	LFHttp	经扩展后台代理的 HTTP / 流式 / WebSocket
model	LFModel	调用PluginX AI 网关（对话 / 流式 / 生图）
user	LFUser	读取插件登录状态与当前用户信息
network	LFNetwork	监听当前标签页的网络请求与响应
agent	LFAgent	创建在 IDE 独立会话中运行的 AI agent 实例（仅限 plugincmd 命令内）

运行环境

已保存的应用以 chrome.userScripts 的 USER_SCRIPT 隔离世界注入页面，和页面自身的 JS 隔离但共享 DOM；只注入顶层页面，不注入 iframe。开发期的 liveDebug 注入会让 LFRuntime.liveDebug 为 true，但不会因此开放额外能力。

工作区桥（LFRuntime.readFile / writeFile / execTerminalCommand）只有终端 run 临时脚本（run / run -c / run --tab / run --target background）可以直接调用。应用源码——无论是 liveDebug、已启用、已安装还是后台应用——直接调用都会编译报错，必须用 LFRuntime.cli.register({ workspace: ['read' | 'write' | 'exec'] }) 注册命令，在 handler 里通过 ctx.workspace.readFile / writeFile / exec 访问；租约只在这次 plugincmd call 执行期间有效。本地命令执行、本地文件访问和 CLI 注册表请求（列出 / 调用 plugincmd）只接受 PluginX 编辑器页面发起，插件应用直接发这类消息会以 EACCES_PERMISSION 拒绝。