asaihost-vue

asaihost-vue

Vue 3 应用宿主框架：引擎运行时（API / WebSocket / AES）、UI 壳层组件、自定义指令，以及基于 public/webmodel/ 的配置引导链。

目录结构

asaihost-vue/
├── index.ts              # 包入口（re-export 插件 + 类型）
├── package.json
├── vite.config.ts
└── src/
    ├── index.ts          # Vue 插件 install（glob 注册 asengine / asui / asdirectives）
    ├── types.ts
    ├── asengine/         # API、WS、AES、provide、路由引擎
    ├── asui/             # 全局 UI 组件
    └── asdirectives/     # v-drag、v-userlevel 等指令

目录

1. 快速开始
2. 在 AsaiCMS monorepo 内使用
3. 独立项目集成
4. LibInit 与 install 约定
5. 配置文件总览
6. 运行时上下文 ujt
7. 扩展业务模块
8. 核心组件与指令
9. 开发与发布 npm 包
10. 约束与后端对应

快速开始

安装

npm install asaihost-vue vue
# 或
yarn add asaihost-vue vue
pnpm add asaihost-vue vue

@noble/ciphers 已作为本包依赖声明（AES-GCM HTTP 降级路径）；无需单独安装。

最小集成（main.ts）

import { createApp } from 'vue';
import App from './App.vue';
import LibInit from './lib/LibInit';           // 见下文「LibInit」
import AsaiHostVue from 'asaihost-vue';

const app = createApp(App);
const { lib } = LibInit();

app.use(AsaiHostVue, lib);   // 必须最先安装
app.mount('#app');

静态资源配置

在 index.html 引入 cfg.js，并将 webmodel/ 目录放到 Vite public/ 下（详见 cfg.js）。

在 AsaiCMS monorepo 内使用

本仓库 webclient 通过路径别名引用插件源码，开发时无需先 npm pack：

// webclient/src/utils/index.ts
import AsaiHostVue from '../plugs/asaihost-vue';

本地构建 npm 产物：

cd webclient/src/plugs/asaihost-vue
npm install
npm run build

独立项目集成

1. Vite 项目

确保 vite.config 能处理本包内的 .vue 与 import.meta.glob（默认 @vitejs/plugin-vue 即可）。

若从 npm 安装（使用 dist/ 预构建产物），直接 import AsaiHostVue from 'asaihost-vue'。

若通过 git submodule / 拷贝源码 联调，可在 package.json 使用 link: 或 file: 指向插件目录，并优先解析 development 条件到 src/index.ts。

2. 复制 LibInit

宿主插件不内置 LibInit——它由业务项目提供 loadts / loadvue / loadv 三个加载器。可从 AsaiCMS webclient/src/lib/LibInit.ts 复制或按需裁剪。

3. 环境变量（.env）

VITE_WEB_PATH=/
VITE_ASAI_AES_KEYBASE64=<与后端 ASAI_AES_KEYBASE64 一致>

4. TypeScript

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "types": ["vite/client"]
  }
}

可从本包导入类型：

import type { VueHostLibLoader, AsaiHostVuePlugin } from 'asaihost-vue';

LibInit 与 install 约定

AsaiHostVue.install(app, lib) 在启动时注册三类资源：

lib 最少需提供：

interface VueHostLibLoader {
  loadts(params: { app; key; eager?; files }): void;
  loadvue(params: { app; eager?; loadfn?; files }): unknown;
  loadv(params: { app; eager?; files }): void;
  loadfn?: { fnvue: typeof defineAsyncComponent };
}

安装顺序：AsaiHostVue 必须早于业务 lib-install 与其它插件。

启动链

app.use(AsaiHostVue, lib)
  → AsaiInitPage.onMounted
      → initweb($vueProxy)     // dirglobal + dirmodel + configrouter + server.json
      → useApi('web') / useWs('web')
  → AsaiWebServer → AsaiComponent（hash 选模块）
  → AsaiWebModule → useInitApp(module) → RouterView

配置文件总览

本插件不读取单一 JSON，而是通过 initweb() 按固定顺序加载一组配置文件，合并到运行时 ujt（window.$GYS.ujt）：

index.html
  └── cfg.js                    → window.$CFG（静态资源路径、标题）
        ↓
initweb() 加载顺序：
  1. sys/dirglobal.json         → 索引全局 sys 片段
  2. sys/dirmodel.json          → 索引模型 JSON
  3. asai/model/configrouter.json → 路由 / 权限（合并各模块 configrouter）
  4. sys/server.json            → API / WS 连接表 → $global.link
  5. 各 webmodel 子文件         → $model.data / $global.sys
  6. .env (VITE_*)              → AES 密钥等构建期变量

静态资源默认通过 AsaiModel.fetchPublic('webmodel/...') 加载（相对 webpath）。

完整配置 — cfg.js（页面级）

在 index.html 中 <script src="webmodel/files/cfg.js"> 引入：

window.$CFG = {
  webpath: '/',   // 静态资源根；设为 '/' 时需与构建 base 一致
  title: '',      // 空则 fallback 到语言包 configweb.webtit
};
window.$CFG.icon = window.$CFG.webpath + 'webmodel/files/favicon.ico';
window.$CFG.logo = window.$CFG.webpath + 'webmodel/files/logo.png';
if (window.$CFG.title) {
  document.title = window.$CFG.title;
  document.querySelector('link[rel="icon"]').href = window.$CFG.icon;
}

完整配置 — dirglobal.json（系统引导索引）

{
  "dir": [
    "asai/global/sysweb.json",
    "asai/global/syspath.json",
    "setting/settingsys.json",
    "setting/settingweb.json"
  ]
}

• initweb() 读取 dir 数组中每个 JSON，浅合并到 $global.sys。
• 业务项目按需增删路径；插件本身只约定 sysweb.json 为核心全局项。

完整配置 — sysweb.json（全局行为，合成示例）

路径：public/webmodel/sys/asai/global/sysweb.json

{
  "webver": "2.0",
  "dttm": "2025-02-28 10:10:10",
  "env": "dev",
  "devlevel": 2,
  "catcherror": 0,
  "zoomid": "asaiwebzoomid",
  "zoomwidth": 1920,
  "zoomheight": 1200,
  "tmbeat": 0,
  "onweblog": true,
  "onwebsitemap": false,
  "onwebws": true,
  "onckuseronline": true,
  "onconsole": 1,
  "tyrobot": "web",
  "local": {
    "lang": "as-lang",
    "theme": "as-theme"
  },
  "aes": {
    "lv": 1,
    "aad": "asai aes aad",
    "keylength": 256,
    "ivlength": 12,
    "algorithm": "AES-GCM"
  }
}

禁止在 JSON 中写 aes.keybase64；使用 VITE_ASAI_AES_KEYBASE64。

完整配置 — dirmodel.json（模型索引）

{
  "dir": [
    "asai/model/configrouter.json",
    "asai/model/sysconfig.json",
    "setting/settinglang.json",
    "setting/settingweb.json"
  ]
}

加载后 $model.data.sys.configrouter 等可被 initweb 用于路由合并。

完整配置 — configrouter.json（路由与权限，合成示例）

路径：public/webmodel/sys/asai/model/configrouter.json
各业务模块可追加 {module}/configrouter.json，rights 合并、其它字段浅合并。

{
  "config": {
    "index": "",
    "login": "user/login",
    "loading": "PageLoad",
    "lv": 3
  },
  "rights": {
    "lv0": ["testkdd", "testkdd/testindex", "user/login", "user/reg", "user/exit", "user/edit"],
    "lv1": ["testkdd/testlv1"],
    "lv2": ["testkdd/testlv2", "admin/userlist"],
    "lv3": ["testkdd/testlv3", "admin/userlist"]
  }
}

Hash 格式：#/模块名/路径/... → $global.location.hasharr。

完整配置 — server.json（API / WS 连接表，合成示例）

路径：public/webmodel/sys/server.json
经 startLink() / initLink() 解析为 $global.link，并缓存到 localStorage 键 as-link。

{
  "servertype": 0,
  "defaultws": "web",
  "api": {
    "default": "web",
    "web": {
      "url": "http://localhost:9198",
      "port": 9198
    },
    "ai": {
      "url": "http://localhost:11434"
    }
  },
  "ws": {
    "default": {
      "close": 0,
      "url": "ws://localhost:9198",
      "port": 9198,
      "sec": 1,
      "worker": 0,
      "config": {
        "tmdeltask": 600000,
        "resend": 0,
        "resendmax": 10
      }
    },
    "web": {
      "close": 0,
      "url": "ws://localhost:9198",
      "port": 9198,
      "sec": 1,
      "worker": 0,
      "config": {
        "tmdeltask": 600000,
        "resend": 0,
        "resendmax": 10
      }
    }
  }
}

api / ws 条目字段

运行时用法

$fn.useApi(ujt, 'web');   // → $fn.api.web（AsaiApi 单例）
$fn.useWs(ujt, 'web');    // → $fn.ws.web（AsaiWs 单例）
$fn.api.web.apiPost('/api/user/login/auth/', body);
$fn.ws.web.wsApi({ ty: 'chat/web', id: '1', db: {} });

完整配置 — .env（构建期，合成示例）

NODE_ENV=development
VITE_ENV_TYPE=development
VITE_OBFUSCATE_ENABLE=0
VITE_MAIN_JS=main
VITE_WEB_PATH=/
VITE_API_URL=/api
VITE_HTTP_HOST=localhost
VITE_HTTP_PORT=9060
VITE_HTTP_API=http://localhost:9198
VITE_DIST_DIR=../webserver/webclient/
VITE_ASAI_AES_KEYBASE64=AsaiFfQ1hMYYvT2N4Y1BhenJ0RjY0M2cxWTMZXdXMVY=

配置 → 运行时映射

cfg.js                          → $global.$cfg
dirglobal.json → sysweb.json…   → $global.sys
dirmodel.json → configrouter…   → $model.data.sys, $global.sys.router
server.json                     → $global.link.api / .ws
  └── useApi / useWs            → $fn.api.* / $fn.ws.*
configrouter.rights             → $global.rlv（访问等级）
VITE_ASAI_AES_KEYBASE64         → $global.sys.aesfns（lv>0 时）

运行时上下文 ujt

安装完成后，各页面通过 inject / 全局属性访问 ujt：

扩展业务模块

1. 在 public/webmodel/{module}/ 放置 configrouter.json、dirmodel.json
2. 将模块名加入 $model.webmodels（业务 bootstrap）
3. Hash 访问 #/{module}/...
4. 可选：lib-install/index.ts 的 install(app, lib) 注册 $engine{module}

核心组件与指令

组件

指令（v-*）

开发与发布 npm 包

本地开发（插件目录）

cd webclient/src/plugs/asaihost-vue
npm install
npm run build          # dist/asaihost-vue.es.js + dist/asaihost-vue.cjs + .d.ts

发布到 npm

cd webclient/src/plugs/asaihost-vue
npm login              # 首次需登录 npmjs.org，scope @asai 需有发布权限
npm publish --access public

prepublishOnly 会自动执行 npm run build。发布内容仅含 dist/、README.md（见 files / .npmignore）。

版本升级

npm version patch   # 或 minor / major
npm publish --access public

package.json 要点

约束与后端对应

架构约束

• 禁止在插件内 cross-import 其它 plugs/*
• 通过业务项目 LibInit 的 loadts / loadvue / loadfn 与宿主耦合
• 与 @estun/asaihost-nodejs（后端）配对使用时，保持 server.json / aes.lv / 环境变量一致

与 asaihost-nodejs 的对应关系

配置文件树（monorepo 参考）

webclient/public/webmodel/
├── files/
│   ├── cfg.js                 ← window.$CFG
│   ├── logo.png
│   └── favicon.ico
└── sys/
    ├── dirglobal.json         ← 引导索引
    ├── dirmodel.json          ← 模型索引
    ├── server.json            ← API/WS 连接表 ★
    └── asai/
        ├── global/
        │   └── sysweb.json    ← 全局 sys ★
        └── model/
            ├── configrouter.json  ← 路由权限 ★
            └── sysconfig.json

测试

# 本插件
npx tsx --test .youmengyu/test/unit/webclient/plugs/asaihost-vue/*.test.mjs

# 仓库全量（含全部 plugs + webserver）
node .youmengyu/test/asaitest.mjs
# 报告：.youmengyu/test/reports/latest/report.html

覆盖：routeAccess ACL、loginConflict 恢复、secureCompare/cookie、userLevels、WS cascade、AsaiWs init/resend 守卫。

配置与行为以本 README 与 useProvide.ts 中 initweb / initLink 源码为准。