@yarlisai/guides

与产品无关的引导式导览引擎 — 声明式步骤、受众定向、生命周期事件。

与产品无关的引导式导览引擎 — 声明式步骤、套餐/角色受众定向，以及生命周期事件，支持 driver.js 和 headless 适配器。

安装

npm install @yarlisai/guides
# for the driver.js adapter:
npm install driver.js

Source: packages/guides · npm · CHANGELOG

@yarlisai/guides 遵循端口/适配器契约：消费者依赖 GuideEngine 端口，并在运行时实例化适配器。引擎本身对 React、i18n、套餐或分析一无所知 — 文案通过解析器传入，受众定向是声明式数据，每个生命周期转换（started、step_viewed、cta_clicked、completed、skipped）都会作为 GuideEvent 发出，供宿主持久化或追踪。

v1 随附两个适配器：

headless — 无 DOM 引擎（从主入口导出），适用于测试、CLI 导览或服务端驱动的导览。
driverjs — 基于 driver.js 的浏览器弹出层。driver.js 是一个可选的对等依赖，该适配器仅通过 @yarlisai/guides/adapters/driverjs 子路径暴露，因此不会打包进不使用它的 bundle 中。CSS 由宿主侧引入（import 'driver.js/dist/driver.css'），可通过可配置的 popoverClass 进行主题定制。

使用方法

import { createGuideEngine, registerGuide, getGuide } from '@yarlisai/guides'

registerGuide({
  id: 'onboarding:build_agent',
  version: '2026.06',
  steps: [
    { id: 'canvas', anchor: 'canvas', i18nKey: 'tour.canvas' },
    {
      id: 'deploy',
      anchor: 'deploy-button',
      i18nKey: 'tour.deploy',
      audience: { roles: ['admin', 'editor'] },
    },
  ],
})

// Adapter selection is config — the chosen module is dynamic-imported.
const engine = await createGuideEngine('driverjs')

engine.start(getGuide('onboarding:build_agent')!, {
  copy: (step) => ({ title: t(`${step.i18nKey}.title`), body: t(`${step.i18nKey}.body`) }),
  labels: { next: t('next'), previous: t('back'), done: t('done'), progress: '{{current}}/{{total}}' },
  context: { plan: 'free', role: 'admin' },
  onEvent: (event) => analytics.track(event),
})

该包的 README 提供了完整的快速入门指南。mybotbox-platform 本身是参考消费者 — apps/sat/lib/guides/ 展示了精简垫片模式，apps/sat/components/onboarding/ 则通过端口驱动产品导览。

@yarlisai/guides

安装

设计理念

使用方法

另请参阅

On this page