@qilin-agent/client-ui-plugin-manager
v3.1.12
Published
Plugin management for the qilin web client: the sidebar Plugins panel installs, enables, disables, retries, and composes installed plugin packages
Readme
description: "从「插件」页管理 profile 的插件组合包、它们的行,以及插件的配置。" kind: "package-reference"
@qilin-agent/client-ui-plugin-manager
English | 中文
概述
使用从设置导航或侧栏的插件行打开的插件管理视图管理 profile 已安装的组合包,以及随安装提供、默认关闭的官方组合包。可以启停组合包及其行、在 Host 读出 spec 之后安装组合包、查看 pnpm 输出、停止一次运行,并启用它新增的包。检查更新把可管理的层与注册表最新版本比较;插件目录搜索 GitHub 上的插件主题。自带配置页的插件在这里编辑。
目录
使用本包
从导航打开插件页。页面首次打开时通过 api-remotes 读取清单与组合包;没有受管 profile 的 Host 上页面显示为不可用。三个分类标签把清单拆开:内置插件列出注册了配置页的官方插件与转正的官方组合包;实验插件列出安装随附、供开启的组合包——开启前保持关闭、没有卸载、属于 beta 功能的带 Beta 标签——并以更多入口收纳目录里暂未推出的实验项;第三方插件列出 profile 持有的组合包。卡片按名称排序,启停组合包不会挪动它的卡片。没有组合包 patch 的依赖不是插件,除非 profile 选中了它才会带异常标签列出。全局配置仍由本视图承载的配置页编辑。
页面条与「更多」列表的返回标题行保持固定:主标题栏与列表共用一个滚动容器,因此标题栏的控件随滚动位置移动,到达收缩位置后沿同一组坐标返回。标题栏保留展开态的高度,移动控件不会改变列表的滚动范围,只滚动一点的列表可以在标题栏完全收缩前停下。有标签页时,副标题与标题滚出视野,标签页在空间允许时停在「刷新」与「添加插件」旁;窄页面上标签页与图标操作在放得下时共处标题下方一行,放不下时标签页保持在操作之上。收缩态在控件下方保留 16px,macOS 叠加窗口标题栏留白,仅在侧栏收起时额外在其上方保留 8px。详情页的标题行随内容一起滚动。
组合包页面在其各部分中首先显示该组合包的详细介绍文档,不带单独的标题:以当前界面语言、带图片的 Markdown 显示该组合包的详细介绍。该文档是组合包 locale/<language>.json 中 meta.detail 指定的 Markdown 文件,没有时为组合包的 README,由 pluginManager.readBundleDetail 按 plugin-detail 的文档顺序读取;不读取组合包声明的仓库。已安装组合包的文档来自其自身文件,不访问网络;按需官方组合包的文档按其提供的版本从 npm 文件 CDN 读取。文档加载期间,该部分显示三行骨架屏;没有文档的组合包不显示该部分;读取失败时说明原因,并提供重试。原始 HTML 会被省略,相对路径的图片从 Host 上该文档旁的位置加载,相对链接保持为文本,文档高度超过该部分的高度上限时在该部分内滚动。文件未安装的组合包(例如按需官方组合包)从 npm 文件 CDN 读取:读取前先询问 Host 的注册表比较,npmmirror 响应最快时,先从 npmmirror 读取该文档及其图片。已安装组合包的读取不等待该比较。任何 profile 变化和连接重置都会重新读取已显示的文档。
Agent Teams Web UI 与 Auto Authorization Review 使用随界面语言切换的本地化名称和描述;Agent Teams 本身由会话标题栏的开关控制,本页不列出它的组合包。该开关写入 profile 选择:被拒绝、或只能等下次启动才生效的写入不会改变控件位置,因此标题栏在开关旁陈述结果,而不是把它藏在悬停里。详情页保留完整 npm 包名;其他包显示简写包名和原始描述。
安装一个组合包
添加插件接受包名(可带版本)、Git 地址、压缩包或本地绝对路径;对话框说明包名就是 README 里 qilin plugin add 后面的那一段。添加插件旁的箭头菜单给出第二条路径:让 Agent 创建插件回到会话视图的可复用空白会话,把创建需求作为普通消息发送,已输入的草稿原样保留。输入框下方的不知道该填什么?展开一段引导,给出三种常见形式各一个示例;填入示例把示例填进输入框。安装先让 Host 读出 spec 指向什么(pluginManager.inspect):列表中已有的名字、注册表没有的名字、没有包的路径、没有组合包 patch 的包,或 pnpm 会拒绝的 spec,都以一句话回到输入框下方,spec 保留可继续编辑。通过检查的 spec 打开安装中界面,展示 Host 读到的包名、一句话简介和版本,pnpm 的命令与输出折叠在查看安装详情之后。每条命令行保持单行并水平滚动;选中文本会连同屏幕外的参数一起选中。安装完成后提供立即启用:启用新组合包、关闭对话框并把列表滚动到它;直接关闭则让它保持已安装但关闭。安装失败时用一行话说明原因——注册表或网络不可达、包不存在、磁盘已满、profile 不可写、pnpm 拦下了构建脚本——pnpm 输出在详情里,重试就在手边;Host 已经把 profile 文件放回原样。pnpm 拦下依赖的安装脚本时,失败界面列出等待允许的包,并以允许这些脚本并重试取代重试;Host 把授权写进 profile 的 pnpm-workspace.yaml(失败的运行保留 pnpm 写入的这个文件)再运行 pnpm,安装完成界面会说明允许了哪些脚本。安装成功不代表模块一定能够激活。失败界面还会标明失败的步骤:安装命令已完成、失败发生在启用组合包时,除了运行原因之外会再说明这一点;详情在已捕获输出之后显示 Host 的完整日志路径(没有终端输出到达详情时则直接说明)。
spec 旁的安装源控件显示这次安装首先询问的源,取自 Host 对 pluginManager.registries() 的回答:pnpm 自己配置的源、配置的备用源(npmmirror 随包提供)、以及必须 http:// 或 https:// 开头的自定义地址。打开对话框时会读取这份清单,并通过 pluginRegistryProbe.fastest() 探测公共源;当 pnpm 自己的源就是 npm 官方源、且已配置镜像时,两者中更快的一个会被选中,直到人另行选择;上一次的手动选择会在对话框之间记住。某个源不可达时安装继续用下一个(私有源则单独询问),对话框会标注每次尝试所用的源;所有源都答不上时,失败说明会列出询问过的源。
安装期间可点击取消安装,对话框显示正在停止安装…,直到 Host 确认。加载组合包的阶段不可取消。确认后对话框回到 spec 输入界面,可再次安装,并用 toast 说明安装已取消;manifest 与 lockfile 已恢复原样,已下载文件可能保留。安装进行中关闭对话框,同样会请求 Host 停止安装,Host 确认后对话框才关闭;Host 正在准备、停止或加载时不能关闭对话框。连接错误不代表取消成功:安装中界面会如此说明,可以再次尝试取消。
检查更新
工具栏上的检查控件让 Host 把每一个可管理的层——包括安装随附的组合包——与注册表最新版本比较(pluginManager.checkUpdates),并把有新版本的层显示为 当前 → 最新。更新通过 Host 的安装通道先删除已安装的包、再以相同的选择状态安装所提供的版本,层在 profile 中的位置保持不变;删除之后安装失败时该包保持未安装,要等下次启动才生效的变更会用 toast 说明原因。注册表答不出的层不给更新入口;没有任何层落后时,该区块显示已是最新。该区块用自带控件关闭;检查失败的原因显示在区块里,可以再检查一次。
浏览插件目录
卡片下方的插件目录搜索 GitHub 上打了 dsh-plugin 主题标签的仓库(pluginManager.catalog),按 star 从多到少排列,并用加载更多翻页。每条结果展示仓库、描述与 star 数,并可在 GitHub 上打开。安装把仓库地址作为 spec 填进安装对话框,由 Host 读取、由人在那里批准安装,与手动输入 spec 完全一致。
更新注册表组合包
从注册表安装、Host 标为 updatable 的第三方组合包,在其页面的行列表上方有 版本 区块。打开页面时向 Host 询问一次它的新版本;重新检查 再问一次。区块显示一行摘要:正在检查;已是最新及上次检查时间;可更新到声明组合包、接受当前 QiLin、未弃用且非预发布的最新版本;新版本需要更新 QiLin 及其所需的 QiLin peer;或检查失败、最后失败的注册表及 重试。有新版本的摘要可展开为每个版本一行,从新到旧,带 dist-tag、预发布与已弃用标签、无法安装的原因、发布日期,以及可安装版本的 更新;列表以已安装版本结尾。其下显示作答的注册表,前面的注册表失败时标为 备选源,旁边是检查时间和 显示预发布版本。检查失败时可通过 详情 展开问过的每个注册表、其角色、失败类型和 pnpm 的原文。从链接、路径、git 或压缩包安装的组合包以及官方组合包不显示版本区块。不会提供更旧的版本。
检查结束后,列表工具栏说明有几个插件可更新、全部已是最新,或部分检查失败,有更新的卡片显示 可更新。详情页头部增加带目标版本的 更新到。
更新 打开确认框,显示已安装版本与目标版本、安装来源,以及安装失败时会保留或重新安装已安装版本。Host 运行更新期间,对话框列出它通告的步骤并保持打开。结果说明新版本已开始运行、需要重启才生效及 Host 给出的原因、目标版本在任何改动前被拒绝、移除已安装版本失败、目标版本未能安装而已安装版本保持不变、更新失败且已重新安装原版本,或重新安装也失败、插件未安装;失败的运行可展开 pnpm 输出。答复丢失时说明结果未知,并重新读取列表。
切换一个组合包
组合包页面在标题下方显示完整包名,也就是在别处安装它所需的 spec。组合包开关改变其层选择。启用了 HMR 的 profile 在操作完成前重组;没有 HMR 的 profile,以及被更高层覆盖的组合包,会以 toast 说明。Host 读不了的组合包带异常标签,其页面给出原因,且不能打开;提供管理组件的组合包保持锁定。 已启用但没有任何行持有 active fiber 的组合包带未运行标签,并显示一行原因:没有可运行的行、声明的行全被关闭、行加载失败、或本次启动没有加载它。任一行恢复运行后两者同时消失。Host 以错误码作答,由页面字典措辞;pnpm 与 Loader 自己的诊断原样显示。页面从卡片与数量中排除每个 profile 都随自身组合携带的组合包(@qilin-agent/base、@qilin-agent/web-app 及各界面应用),即使 profile 将它们列为依赖或 Host 报告了异常;Host 清单仍保留完整数据。解析权归 profile 的随附组合包——装进 profile 的副本优先于安装实例、因而可原地升级的那种——则会列出:其卡片显示 profile 解析到的版本,层开关连同原因一并锁定,因为摘除该条目无法在下次加载后存活;升级本身由可更新列表执行,而该层的行仍可逐条开关。
切换组合包里的一行
组合包页面上行的开关调用 pluginManager.setPluginEnabled,往 profile 的 cordis.patch.yml 写入该行的 disabled 覆盖。启用了 HMR 的 profile 的树随即重组,该行的宿主半区卸下或挂上,组合包其余部分照常运行,页面无需重载即跟随客户端模块图。行按 Host 运行它们的 fiber 阶段显示状态。开关只出现在已打开的组合包上;没有存活条目的行,以及 Host 不通过 profile patch 寻址的行,带着 Host 的原因锁定。超过十行的列表带一个按行 id 筛选的输入框。
配置页
当某个组合包贡献了自己的 plugins.bundle.config 条目时,该条目就是这个组合包的配置界面:页面把它渲染在组合包页面上,自身从不点名任何可配置插件。
自带配置的插件把配置渲染在本页,通过本页声明的三个 slot:plugins.item(list)用于官方插件,按其 label 列在官方分组里;plugins.bundle.config(以组合包的包名为键)用于组合包自己的配置,显示在组合包页面的描述与行之间;plugins.row.config(以 <包名>#<行 id> 为键)用于某一行的配置,该行因此获得「配置」控件并打开行页面——标题行显示行标题、行 id 与模块,描述取组合包描述,缺失时回落到条目的 view: 'summary'。页面通过 owner props 向每个条目索取两种视图:view: 'summary' 是标题下的一句话简介,view: 'page' 是带自己保存控件的表单;当 page 视图对应的 Host 条目由设置文档服务时,还会给出 form——页面从 ctx.configForms 取到的共享 ConfigPageForm(已接受的值加一个原子 mutate),自管控件的条目可以忽略它。只有保存才写入:页面负责画标题、图标与面包屑,条目的表单在离开页面时丢弃暂存的修改。安装随附的四个宿主平面配置页——shell 执行器、agent loop、子智能体模型选择、DeepSeek 搜索提供方——来自 ui-settings-plugins,在 Host 服务其命名空间期间注册。组合包的浏览器半侧用同样的方式注册。
ctx.slots.inject('plugins.bundle.config', () => ctx.slots.register({
name: 'plugins.bundle.config',
key: '@acme/qilin-sidebar-bundle',
locale: 'acmeSidebar',
}, ({ t, view, form }) => view === 'page' ? <SidebarForm t={t} form={form} /> : null))注册只在组合包开启期间存在,因此关闭的组合包不显示配置。
理解实现
页面两个列表与其「实验性」徽标都读取安装方的 bundle 准入,来源是 @qilin-agent/official-bundles:主列表始终持有的可选 bundle、留待 profile 启用后由「更多」列表排在最后的那些、页面隐藏的内建 profile 层,以及带徽标的 bundle。「更多」列表只放带徽标的 bundle,而名单不再标记为实验性的 bundle 一律留在「内置插件」标签里——转正就是从该集合删除一个名字。因此安装方提供的 bundle 从同一个共享包到达页面,而不是靠客户端的包名副本。
插件管理依据 profile 的依赖记录:已安装组合包可启停、可移除,随安装提供的组合包保持锁定。profile 与安装都不持有的选中组合包同样提供卸载,且仅把它从 profile 的组合包列表移除。这一区分不决定启动失败策略。
注册
浏览器插件通过 ctx.slots.inject() 把「插件」页面注册为设置外壳的 settings.section 条目(id 为 plugins、order 15、导航文案取自本包字典),页面跟随 slot 延迟声明、本地化变化与销毁。页面为全局页面,不属于任何 Session;工作区不再有自己的「插件」面板与侧栏入口。跨插件导航走 ctx.pluginNavigation:先通过 ctx.settingsShell.open('plugins') 打开该设置分区,再把共享导航 store 指向列表或某个组合包。
store
PluginManagerController 拥有组合包视图、忙碌键、提示、安装进度和卸载确认。每次读取先问清单 Host 是否管理着 profile,再把 listBundles 与 listPlugins 合成每个组合包一份视图,其行携带存活条目的启停状态与 fiber 阶段。它合并重叠读取,在操作后、收到 plugin-manager/changed 时以及重连后刷新,并在销毁后忽略晚到结果。每个官方行显示 Host 从组合包自带的 locale 导出文件读取的本地化文案,回退到技术名与清单 description;管理器自带文案的组合包保持自带文案。 手动刷新保留已缓存的列表,在「刷新」控件上显示 spinner,直至读取与它发起的更新检查都完成且至少经过 400 ms,并忽略重复请求;后台读取既不显示它,也不做检查。已加载列表后,一次失败的手动刷新保留缓存内容,并在全页 overlay 座位上弹出 refresh-failed toast,即使离开面板也会显示;在任何成功读取之前,失败就地显示并附「重试」。安装输出按 job id 分组。安装对话框沿 idle → checking → starting → running → done | failed 推进,cancelling 与 applying 按 Host 的报告呈现。检查在一个 AbortController 下运行,返回编辑或关闭会中止它并丢弃其结果;运行只能通过 pluginManager.cancelInstall 停止,对话框等待其答复。Host 无法应用的变更、要等重启的变更、被更高层覆盖的变更,都是会自行消失的 toast。检查更新与目录搜索是各自的读取:状态与失败文本都留在发起它们的区块里,因此一次失败的查询不会改动卡片。
配置 slot
页面的 main 注册把 plugins.item、plugins.bundle.config、plugins.row.config、plugins.add.actions、plugins.tab 与 plugins.detail.* 各列声明为子 slot,因此它们与页面同生,注册方的 ctx.slots.inject 会等到它们出现。configLedgerSource 把三份账本投影成一个可观察对象——按账本顺序排列、标签按当前语言解析的官方条目,以及组合包和行的键——在账本或语言变化前保持缓存;页面把它作为 useConfigLedger 绑在 store 旁边,自身从不点名任何可配置插件。打开的是哪一页是页面本地状态:卡片、某个组合包,或某个官方插件。其他 Client 插件注入 pluginNavigation,调用 ctx.pluginNavigation.openBundle(packageName) 即可打开组合包详情,不改变当前 Session;该通道先打开「插件」页,再把包名交给已挂载页面的展示动作,组合包不存在时显示列表。注册与做出它的浏览器半侧同生共死。qilin-client-modules 只把一个包的浏览器半侧挂在说明符恰为包名的那一行 Loader 行上,所以组合包为自己注册的页面,都会在那一行被关闭时一起消失;需要在其他行关闭时仍保留页面的子插件,应作为独立的包发布。
进一步探索
这些页面覆盖设置标签页、Remote 调用与 Host 侧管理器。
- ui-settings——页面注册进的标签页列表;ui-settings-plugins——渲染该标签页的「插件」分区。
- api-remotes——
pluginManager.*与pluginInventory.*背后的 Remote BFF 面。 - plugin-manager——本页驱动的 Host 侧管理器。
- official bundles——本页读取的 bundle 准入与位置名单。
- ui-settings-plugins——注册进本页 slot 的官方配置页。
模型体验
无,本包是浏览器侧的管理界面,不注册任何面向模型的内容。
KV Cache 影响
无;本包既不组装也不发送 provider 请求。
已知限制与延期工作
这些限制界定了管理视图的范围;它们是当前包的约束。
- 只管理组合包——没有组合包 patch 的依赖在安装前就被拒绝;profile 里已有的这类依赖不上页面,除非 profile 选中了它;加载普通插件模块仍是文件操作。
- 行只显示阶段,不显示原因——失败的行只显示为失败,没有 Host 的错误文本;Host 日志里有。
- 一次只能安装一个——对话框一次运行一个 pnpm 命令;第二个 spec 要等前一个完成。
- 更新只跟随注册表的
latest标签——检查只针对 profile 管理的层,并把它们升到最新版本;要锁定某个具体版本仍须手动输入 spec。 - 管理视图是设置分区——分区注册与其子 slot 归本包所有;工作区面板与侧栏入口已移除。上游的侧栏面板交互仍属延期(对齐边界)。
- 丢失的安装应答无法恢复——Host 不提供
waitForInstall,因此对话框只报告传输失败,不会向 Host 追问该次运行的结果。
开发备注
无。
