@4399ywkf/yuyu
v0.2.18
Published
YuYu 页面助手浏览器 SDK:ESM 给打包接入,IIFE 给 script 标签接入
Readme
YuYu 页面助手
@4399ywkf/yuyu 是浏览器端页面助手 SDK:服务端 Agent 通过它读取并操作用户正在看的页面。提供 ESM、Node 可用的协议子路径,以及 script 标签接入产物。
安装
pnpm add @4399ywkf/yuyu react react-domReact 19 与 React DOM 19 是 peer dependencies,由宿主提供,避免页面中出现两份 React。
ESM 接入
import { init, version } from '@4399ywkf/yuyu';
const assistant = init({
endpoint: 'https://assistant.example.com/api',
hostId: 'example-host',
theme: 'system',
panelMode: 'floating',
});
assistant.open();
console.log(version);模块可以在服务端 import,init 应在浏览器挂载后调用。ESM 的 init 返回实例,外部依赖由宿主打包器解析。
宿主的登录态是短期 token、平时由自己的 HTTP 层在请求前换票时,传 fetch 让 SDK 的请求也走这一层;不传时用浏览器的 fetch,token 过期后 SDK 会显示登录卡片。
init({
endpoint: '/api/assistant',
hostId: 'example-host',
// 请求前补齐 token;401 时换票后重试一次,仍是 401 才算未登录
fetch: (url, init) => authedFetch(url, init),
});侧边面板(panelMode: 'sidebar')默认宽 420px,用户可拖左边缘在 360px 到视口宽 60% 之间调宽;它只覆盖页面右侧,不改宿主布局。要做成分栏,由宿主按面板宿主元素 <ywkf-yuyu> 的属性让位:data-panel-mode 是当前模式,面板打开时带 data-panel-open,调过宽度后 data-panel-width 是当前宽度(px),拖动期间带 data-panel-resizing;窄于 768px 时面板占满视口,不必让位。
宿主有固定顶栏、想让侧边面板停在顶栏下面当布局的一栏时,在 <ywkf-yuyu> 上设 --ywkf-sidebar-top(顶栏高度);设 --ywkf-sidebar-z-index 可以把侧边面板降到宿主弹层之下,顶栏、抽屉的弹层就能盖在面板上。侧边面板左边默认是一条 1px 实线;宿主自己的分栏线是别的画法(比如上下淡出)时,用 --ywkf-sidebar-divider 给它换一张 CSS 图像(linear-gradient(...) 这类,不能直接写颜色),两条线就是同一种。三个变量只影响侧边面板。
ywkf-yuyu {
--ywkf-sidebar-top: 56px;
--ywkf-sidebar-z-index: 999;
--ywkf-sidebar-divider: linear-gradient(transparent, #e9e9ed 50%, transparent);
}
@media (min-width: 768px) {
html:has(> ywkf-yuyu[data-panel-mode='sidebar'][data-panel-open]) body {
padding-inline-end: var(--dock-width, 420px);
}
}让位宽度跟着用户拖动走:把 data-panel-width 抄到页面能用的变量上。
const host = document.querySelector('ywkf-yuyu')!;
new MutationObserver(() => {
const width = host.getAttribute('data-panel-width');
if (width) document.documentElement.style.setProperty('--dock-width', `${width}px`);
}).observe(host, { attributeFilter: ['data-panel-width'] });协议可以独立在 Node 中使用:
import { CLIENT_TOOLS } from '@4399ywkf/yuyu/protocol';
console.log(CLIENT_TOOLS);包只提供 ESM,不支持 require();Node 需要 22 或更高版本。
script 标签接入
<script
src="/yuyu/loader.iife.js"
data-endpoint="https://assistant.example.com/api"
data-host-id="example-host"
async
></script>加载后通过 YwkfYuYu.init(config) 初始化;主包尚未加载时,API 调用会排队。也可以直接加载 assistant.iife.js,使用同一个 YwkfYuYu 全局对象。全局对象的 init 不返回实例,后续调用 YwkfYuYu.open() 等方法。
loader.iife.js 与 assistant.iife.js 是浏览器脚本,不能在 Node 中 import 验证或执行。部署时须复制并统一更新完整 dist 目录,不能只复制入口脚本;内部分包、CSS、worker、备用资源和 renderers/ 必须保持相对路径不变。
技能与公开子路径
除主入口和 ./protocol 外,包还公开:
./loader.iife.js./assistant.iife.js./renderers/*./skills/page-operator/SKILL.md./package.json
需要在 Node 中定位技能文件时:
import { fileURLToPath } from 'node:url';
const skillPath = fileURLToPath(
import.meta.resolve('@4399ywkf/yuyu/skills/page-operator/SKILL.md'),
);许可
本包使用 UNLICENSED / 保留所有权利,使用权限由版权所有者另行授权。npm 公共下载不构成开源许可。
第三方组件适用各自许可证,见 THIRD_PARTY_NOTICES.md。
