# asaihost-vue 中文文档

规范地址：https://npmcn.com/package/asaihost-vue/

版本：0\.0\.24
npm 元数据更新时间：2026-11-03T03:30:13.068Z
中文译文更新时间：2026-11-03T03:56:28.295Z
软件包许可：ISC

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/asaihost-vue
原文对照：https://npmcn.com/package/asaihost-vue/?lang=original
项目主页：https://github.com/asai-cc/asaicms-v1/tree/main/webclient/src/plugs/asaihost-vue#readme
源码仓库：https://github.com/asai-cc/asaicms-v1/webclient/src/plugs/asaihost-vue

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.9 MB，177 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：2 个
- 首次发布：2026-07-06T07:19:31.408Z
- 最新版本发布：2026-11-03T03:30:12.897Z
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

AsaiWeb CMS Vue 3主机插件-引擎运行时，UI shell，指令，和webmodel引导

## 安装

```sh
npm install asaihost-vue
```

也可以使用：`pnpm add asaihost-vue`、`yarn add asaihost-vue`、`bun add asaihost-vue`

## README

# asaihost-vue

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

| 项 | 值 |
| --- | --- |
| **npm 包名** | `asaihost-vue` |
| **插件入口** | `index.ts`（monorepo 源码）/ `dist/asaihost-vue.es.js`（发布后） |
| **运行时配置根** | `public/webmodel/` + `cfg.js` |
| **对等依赖** | `vue ^3.4` |

### 目录结构

```
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.  [快速开始](https://npmcn.com/package/asaihost-vue/#readme-%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B)
2.  [在 AsaiCMS monorepo 内使用](https://npmcn.com/package/asaihost-vue/#readme-%E5%9C%A8-asaicms-monorepo-%E5%86%85%E4%BD%BF%E7%94%A8)
3.  [独立项目集成](https://npmcn.com/package/asaihost-vue/#readme-%E7%8B%AC%E7%AB%8B%E9%A1%B9%E7%9B%AE%E9%9B%86%E6%88%90)
4.  [LibInit 与 install 约定](https://npmcn.com/package/asaihost-vue/#readme-libinit-%E4%B8%8E-install-%E7%BA%A6%E5%AE%9A)
5.  [配置文件总览](https://npmcn.com/package/asaihost-vue/#readme-%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%E6%80%BB%E8%A7%88)
6.  [运行时上下文 ujt](https://npmcn.com/package/asaihost-vue/#readme-%E8%BF%90%E8%A1%8C%E6%97%B6%E4%B8%8A%E4%B8%8B%E6%96%87-ujt)
7.  [扩展业务模块](https://npmcn.com/package/asaihost-vue/#readme-%E6%89%A9%E5%B1%95%E4%B8%9A%E5%8A%A1%E6%A8%A1%E5%9D%97)
8.  [核心组件与指令](https://npmcn.com/package/asaihost-vue/#readme-%E6%A0%B8%E5%BF%83%E7%BB%84%E4%BB%B6%E4%B8%8E%E6%8C%87%E4%BB%A4)
9.  [开发与发布 npm 包](https://npmcn.com/package/asaihost-vue/#readme-%E5%BC%80%E5%8F%91%E4%B8%8E%E5%8F%91%E5%B8%83-npm-%E5%8C%85)
10.  [约束与后端对应](https://npmcn.com/package/asaihost-vue/#readme-%E7%BA%A6%E6%9D%9F%E4%B8%8E%E5%90%8E%E7%AB%AF%E5%AF%B9%E5%BA%94)

* * *

## 快速开始

### 安装

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

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

### 最小集成（main.ts）

```typescript
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](https://npmcn.com/package/asaihost-vue/#readme-%E5%AE%8C%E6%95%B4%E9%85%8D%E7%BD%AE--cfgjs%E9%A1%B5%E9%9D%A2%E7%BA%A7)）。

* * *

## 在 AsaiCMS monorepo 内使用

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

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

本地构建 npm 产物：

```bash
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）

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

### 4\. TypeScript

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

可从本包导入类型：

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

* * *

## LibInit 与 install 约定

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

| 步骤 | lib 方法 | 注册内容 |
| --- | --- | --- |
| 1 | `loadts` | `$engineasai`：`asengine/common/*.ts`、`useApi` / `useWs` / `useAES` / `useProvide` 等 |
| 2 | `loadvue` | `asui/*/*.vue` 全局组件（懒加载） |
| 3 | `loadv` | `asdirectives/*/index.ts` 自定义指令 |

`lib` 最少需提供：

```typescript
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 密钥等构建期变量
```

| 文件 | 典型路径 | 进 Git | 挂载到 |
| --- | --- | --- | --- |
| **cfg.js** | `public/webmodel/files/cfg.js` | ✅ | `window.$CFG` → `$global.$cfg` |
| **dirglobal.json** | `public/webmodel/sys/dirglobal.json` | ✅ | `$global.sys`（合并） |
| **dirmodel.json** | `public/webmodel/sys/dirmodel.json` | ✅ | `$model.data.sys` |
| **configrouter.json** | `public/webmodel/sys/asai/model/configrouter.json` + 各模块 | ✅ | `$global.sys.router` |
| **server.json** | `public/webmodel/sys/server.json` | ✅ | `$global.link.api` / `.ws` |
| **sysweb.json** 等 | 由 dirglobal / dirmodel 索引 | ✅ | `$global.sys.*` |
| **.env.development** | 项目根 `.env.development` | ✅ 模板 | `import.meta.env.VITE_*` |

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

* * *

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

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

```javascript
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;
}
```

| 字段 | 说明 |
| --- | --- |
| `webpath` | 静态资源前缀；影响 `getWebPath()`、`AsSvg` 等 |
| `title` | 浏览器标题（优先于语言包） |
| `logo` / `icon` | 由脚本派生，加载页/错误页使用 |

* * *

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

```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`

```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"
  }
}
```

| 字段 | 说明 |
| --- | --- |
| `devlevel` | \>0 时开发模式自动生成路由菜单 |
| `catcherror` | 1=全局 error / unhandledrejection 上报 |
| `onwebws` | 1=启动用户 WS（`publish/web` 监听） |
| `onweblog` | 远程客户端日志 |
| `onconsole` | WS/API 耗时控制台输出 |
| `tyrobot` | 默认机器人类型 → `$fn.apisys` / `$fn.wssys` 别名 |
| `local.lang` / `local.theme` | localStorage 键名 |
| `aes.lv` | 与后端 `asaihost.json` 的 `aes.lv` 对齐；>1 需 `.env` 密钥 |

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

* * *

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

```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 合并、其它字段浅合并**。

```json
{
  "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"]
  }
}
```

| 字段 | 说明 |
| --- | --- |
| `config.index` | 默认首页 hash 段 |
| `config.login` | 未登录跳转 hash |
| `config.loading` | 加载组件名 |
| `config.lv` | 默认访问等级 |
| `rights.lv0`~`lv3` | hash 路径片段列表；`AsaiInitPage` 计算 `$global.rlv` |

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

* * *

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

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

```json
{
  "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 条目字段

| 字段 | 说明 |
| --- | --- |
| `url` | 完整地址；也可仅 `port`，由 `As.getUrlByCfg` 拼 hostname |
| `port` | 端口（DEV 下 Vite 代理 `/api` 时不直连后端端口） |
| 字符串值 | 引用同名键，如 `"weld": "default"` |
| `close` | 1=不建连 |
| `sec` | 1=WS 需登录 token 才建连 |
| `worker` | 1=Web Worker 模式 WS |
| `config.tmdeltask` | wsApi 回调 Map 清理间隔（ms） |
| `config.resend` / `resendmax` | 重发策略 |

### 运行时用法

```typescript
$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（构建期，合成示例）

```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=
```

| 变量 | 说明 |
| --- | --- |
| `VITE_ASAI_AES_KEYBASE64` | **须与后端 `ASAI_AES_KEYBASE64` 一致** |
| `VITE_HTTP_API` | 参考用；DEV 实际 API 走 Vite 代理 `/api` |
| `VITE_WEB_PATH` | 构建 base，与 `$CFG.webpath` 对齐 |

* * *

## 配置 → 运行时映射

```
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`：

| 键 | 职责 |
| --- | --- |
| `$global` | 用户、hash、link、sys、主题 |
| `$fn` | API/WS、As/AsCode、路由、登录 |
| `$model` | 模块 dirmodel、comps |
| `$db` / `$dbwork` | 模块响应式数据 |
| `$ws` | WS 推送（wssys） |

* * *

## 扩展业务模块

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}`

* * *

## 核心组件与指令

### 组件

| 组件 | 说明 |
| --- | --- |
| `AsaiInitPage` | 首屏：initweb / link / lang / WS |
| `AsaiWebServer` | 根容器 |
| `AsaiWebModule` | 模块：initAppModel + 模块 WS |
| `PageLoadClient` / `Server` / `Ws` / `Err` | 加载与错误态 |
| `AsPageBusy` | 全局 busy |
| `PopBox` / `PopMsg` / `PopTip` | 弹层与消息 |

### 指令（`v-*`）

| 指令 | 说明 |
| --- | --- |
| `v-drag` | 指针拖拽（绝对定位 translate） |
| `v-longpress` | 长按触发回调 |
| `v-scrollbottom` | 列表在底部时自动滚底 |
| `v-fullscreen` | 点击/双击切换目标全屏 class |
| `v-userlevel` | 用户等级不足时遮盖 |
| `v-levelread` | 无读权限时遮盖 |
| `v-dbpointerdown` | 300ms 内双击 pointerdown |
| `v-dragzoom` | 缩放场景下拖拽（弹窗标题栏） |
| `v-popresizezoom` | 缩放场景下右下角 resize |
| `v-resizeflexwidthzoom` | 拖拽分隔条调整宽高 |

* * *

## 开发与发布 npm 包

### 本地开发（插件目录）

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

### 发布到 npm

```bash
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`）。

### 版本升级

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

### package.json 要点

| 字段 | 说明 |
| --- | --- |
| `name` | `asaihost-vue` |
| `peerDependencies.vue` | `^3.4.0` |
| `dependencies.@noble/ciphers` | AES-GCM 纯 JS 降级 |
| `exports.development` | monorepo 源码 `./index.ts` |
| `publishConfig.access` | `public` |

* * *

## 约束与后端对应

### 架构约束

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

### 与 asaihost-nodejs 的对应关系

| 前端 server.json | 后端 asaihost.json |
| --- | --- |
| `api.web.port` 9198 | `hosts.default.port` 9198 |
| `ws.web.port` 9198 | `hosts.default.ws: 1` |
| `aes.lv` | `aes.lv`（密钥均走 env，不进 JSON） |
| `ws.sec: 1` | `security.requireAuth` + 登录 token |

* * *

## 配置文件树（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
```

* * *

## 测试

```bash
# 本插件
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` 源码为准。_

## 常见问题

### asaihost-vue 是什么？

AsaiWeb CMS Vue 3主机插件-引擎运行时，UI shell，指令，和webmodel引导

### 如何安装 asaihost-vue？

在项目目录运行 npm install asaihost-vue，或使用 pnpm add / yarn add / bun add。

### asaihost-vue 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### asaihost-vue 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### asaihost-vue 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### asaihost-vue 可以商用吗？

asaihost-vue 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### asaihost-vue 还在维护吗？

最新版本 0\.0\.24 发布于 2026/11/03（今天）；至今共发布 22 个版本，其中过去 12 个月发布了 22 个；首次发布于 2026/07/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。