@hjsy/vue-ai-assistant-badge 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 本文件遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 与
 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## [Unreleased]
+
+### Added
+
+- 子路径导出 `@hjsy/vue-ai-assistant-badge/vite`：`aiAssistantProxy()` Vite 插件把 `/v1` 开发态代理
+  打包进组件，宿主只需在 vite.config.ts 加一行并指定服务地址（target → `VITE_AI_API_URL` → 内置兜底
+  三级解析，兜底时终端提醒改地址；宿主已配同前缀代理时自动让位）。
+- `postinstall` 接入提示：安装后自动打印两步指引（bootstrap.ts 典型位置 + 要粘贴的代码；
+  代理插件用法）；CI 静默，pnpm 10+ 需 `pnpm approve-builds` 批准。
+- `vite` 声明为可选 peerDependency（仅使用 `/vite` 子路径时需要）。
+- 单测覆盖代理插件的前缀注入、地址优先级、宿主让位与兜底提示。
+
 ## 0.1.0
 
 ### Added

package/README.md

@@ -34,6 +34,7 @@
 - 🔐 **权限双校验**：跳转前校验菜单归属，触发按钮前再校验按钮权限码
 - 🎨 **样式自带**：CSS 以运行时注入方式内置，可覆盖 CSS 变量换肤，无需宿主配 Tailwind
 - 🧩 **可插拔适配层**：`@hjsy/vue-ai-assistant-badge/adapters/vben` 提供 vben 工程的一行接入
+- 🚇 **开发代理内置**：`@hjsy/vue-ai-assistant-badge/vite` 导出 Vite 插件，`/v1` 代理不用再手写，只需给服务地址
 
 ## 安装
 
@@ -45,6 +46,25 @@ pnpm add @hjsy/vue-ai-assistant-badge
 
 要求：Node ≥ 18，Vue ≥ 3.4。
 
+安装完成后，终端会自动打印接入提示（bootstrap.ts 的典型位置、要粘贴的代码、代理插件用法）。
+若用 pnpm 10+ 且没看到提示，先批准构建脚本：`pnpm approve-builds`，
+或在根 `pnpm-workspace.yaml` 的 `allowBuilds` 加 `"@hjsy/vue-ai-assistant-badge": true`。
+
+### 开发态代理：一行接入，只改地址
+
+`/v1 → AI 判定服务` 的反向代理已打包成 Vite 插件（子路径 `/vite`，仅 dev server 生效）：
+
+```ts
+// 应用的 vite.config.ts（vben 工程放返回值的 vite.plugins；标准工程放顶层 plugins）
+import { aiAssistantProxy } from '@hjsy/vue-ai-assistant-badge/vite';
+
+plugins: [aiAssistantProxy({ target: 'http://你的AI服务地址:48080' })];
+```
+
+`target` 也可省略：插件会读 `.env.*` / 环境变量里的 `VITE_AI_API_URL`；
+都读不到时用内置兜底地址并在终端提醒改地址。前缀可用 `prefix` 改（需与 `ask` 的 `baseUrl` 一致）；
+宿主已手写同前缀代理时插件自动让位。
+
 ## 快速开始
 
 最小可用示例（自带 fetch 请求客户端 + mock 权限源）：
@@ -56,7 +76,7 @@ import { createAiAssistantPlugin, createFetchAskClient } from '@hjsy/vue-ai-assi
 import App from './app.vue';
 
 const ask = createFetchAskClient({
-  baseUrl: '/v1', // 结构化判定服务前缀，开发态交给 devServer 代理
+  baseUrl: '/v1', // 结构化判定服务前缀，开发态由上方 aiAssistantProxy 内置代理
   getHeaders: () => ({ Authorization: `Bearer ${getToken()}` }),
 });
 
@@ -262,6 +282,7 @@ npm run release:beta      # 打 beta tag：npm i @hjsy/vue-ai-assistant-badge@be
 | `registerAiAction` / `dispatchAiAction` / `AI_ACTION_EVENT` | 按钮动作注册与派发 |
 | `useDraggableBadge` / `useTypewriter` | 拖拽与打字机逻辑，供自定义渲染复用 |
 | `AI_ASSISTANT_CSS` / `ensureStyles` | 内置样式（SSR 可自行内联） |
+| `aiAssistantProxy`（子路径 `/vite`） | 内置 `/v1` 开发态代理的 Vite 插件，宿主只改服务地址 |
 | `showToast` / `toast` | 内置轻提示 |
 
 ## 常见问题

package/dist/vite.d.ts

@@ -0,0 +1,23 @@
+import { Plugin } from "vite";
+/** 默认代理前缀（与 createFetchAskClient 的 baseUrl 默认值一致） */
+declare const DEFAULT_AI_PROXY_PREFIX = "/v1";
+/** 默认环境变量名（.env.development 等文件中配置服务地址） */
+declare const DEFAULT_AI_PROXY_ENV_VAR = "VITE_AI_API_URL";
+/** 未配置任何地址时的兜底目标（仅开发联调用，终端会给出改地址提示） */
+declare const DEFAULT_AI_PROXY_TARGET = "http://192.168.1.10:48080";
+interface AiAssistantProxyOptions {
+  /** 代理前缀，默认 /v1；需与 ask 客户端的 baseUrl 保持一致 */
+  prefix?: string;
+  /** AI 判定服务地址；不传则读 envVar，仍无则用 fallbackTarget 并给出提示 */
+  target?: string;
+  /** 读取服务地址的环境变量名，默认 VITE_AI_API_URL */
+  envVar?: string;
+  /** 兜底服务地址，默认 DEFAULT_AI_PROXY_TARGET */
+  fallbackTarget?: string;
+  /** 是否转发 WebSocket，默认 true */
+  ws?: boolean;
+  /** 是否改写请求头中的 Host 为目标地址，默认 true */
+  changeOrigin?: boolean;
+}
+declare function aiAssistantProxy(options?: AiAssistantProxyOptions): Plugin;
+export { AiAssistantProxyOptions, DEFAULT_AI_PROXY_ENV_VAR, DEFAULT_AI_PROXY_PREFIX, DEFAULT_AI_PROXY_TARGET, aiAssistantProxy };

package/dist/vite.mjs

@@ -0,0 +1,53 @@
+import { loadEnv } from "vite";
+// src/vite.ts
+/**
+* 内置开发态反向代理插件：把 systemone AI 判定服务的 /v1 代理打包进组件，
+* 宿主只需在 vite.config.ts 的 plugins 里加一行，最多改一个服务地址。
+*
+* 用法（vben 工程的 vite.config.ts 返回结构中）：
+* ```ts
+* import { aiAssistantProxy } from '@hjsy/vue-ai-assistant-badge/vite';
+*
+* return {
+*   application: {},
+*   vite: { plugins: [aiAssistantProxy()] },
+* };
+* ```
+*
+* 地址解析优先级：
+* 1. 显式传入的 `target`
+* 2. .env.* / 环境变量里的 `envVar`（默认 VITE_AI_API_URL）
+* 3. 内置兜底 `fallbackTarget`（会在终端提示用户改成自己的地址）
+*
+* 宿主若已自行配置了同前缀代理，本插件自动让位、不覆盖。
+*/
+/** 默认代理前缀（与 createFetchAskClient 的 baseUrl 默认值一致） */
+const DEFAULT_AI_PROXY_PREFIX = "/v1";
+/** 默认环境变量名（.env.development 等文件中配置服务地址） */
+const DEFAULT_AI_PROXY_ENV_VAR = "VITE_AI_API_URL";
+/** 未配置任何地址时的兜底目标（仅开发联调用，终端会给出改地址提示） */
+const DEFAULT_AI_PROXY_TARGET = "http://192.168.1.10:48080";
+function aiAssistantProxy(options = {}) {
+	const { prefix = "/v1", envVar = DEFAULT_AI_PROXY_ENV_VAR, fallbackTarget = DEFAULT_AI_PROXY_TARGET, changeOrigin = true, ws = true, target } = options;
+	let usedFallback = false;
+	return {
+		name: "hjsy-ai-assistant-proxy",
+		apply: "serve",
+		config(config, { mode }) {
+			if ((config?.server?.proxy ?? {})[prefix]) return;
+			const env = loadEnv(mode ?? "development", process.cwd());
+			const resolved = target || env[envVar] || process.env[envVar] || "";
+			usedFallback = !resolved;
+			const proxy = {
+				changeOrigin,
+				target: resolved || fallbackTarget,
+				ws
+			};
+			return { server: { proxy: { [prefix]: proxy } } };
+		},
+		configResolved(config) {
+			if (usedFallback) config.logger.warn(`[aiAssistantProxy] 未检测到 AI 服务地址，暂使用内置默认 ${fallbackTarget}；请在 .env 配置 ${envVar}=http://你的服务地址，或传 aiAssistantProxy({ target })`);
+		}
+	};
+}
+export { DEFAULT_AI_PROXY_ENV_VAR, DEFAULT_AI_PROXY_PREFIX, DEFAULT_AI_PROXY_TARGET, aiAssistantProxy };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hjsy/vue-ai-assistant-badge",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "可拖拽的全局 AI 助手角标组件（Vue 3）：自然语言识别菜单与按钮权限意图，自动跳转页面并触发按钮动作",
   "keywords": [
     "vue",
@@ -35,10 +35,15 @@
       "types": "./dist/adapters/vben.d.ts",
       "default": "./dist/adapters/vben.mjs"
     },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.mjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "scripts/postinstall.mjs",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -48,6 +53,7 @@
   },
   "scripts": {
     "dev": "vite",
+    "postinstall": "node scripts/postinstall.mjs",
     "build": "tsdown",
     "preview": "vite preview",
     "typecheck": "vue-tsc --noEmit",
@@ -64,8 +70,14 @@
     "prepublishOnly": "npm run pack:check"
   },
   "peerDependencies": {
+    "vite": ">=5",
     "vue": "^3.4.0"
   },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "@vitejs/plugin-vue": "^6.0.0",

package/scripts/postinstall.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * postinstall：安装完成后打印接入指引。
+ * 内容只有两步——改代理地址（内置 Vite 插件）、粘 bootstrap 代码（给出文件位置）。
+ * CI 环境静默跳过；pnpm 10+ 需先批准构建脚本才会执行（见 README「安装」）。
+ */
+import { exit } from 'node:process';
+
+if (process.env.CI) {
+  exit(0);
+}
+
+const BOLD = '\u001B[1m';
+const CYAN = '\u001B[36m';
+const DIM = '\u001B[2m';
+const RESET = '\u001B[0m';
+
+const bootstrapSnippet = [
+  '// bootstrap.ts 中，app.use(router) 之后',
+  "import { createAiAssistantPlugin, createFetchAskClient } from '@hjsy/vue-ai-assistant-badge';",
+  "import { useAccessStore } from '@vben/stores';",
+  "import { router } from './router';",
+  '',
+  'const accessStore = useAccessStore();',
+  '',
+  'const ask = createFetchAskClient({',
+  "  baseUrl: '/v1', // 与内置代理前缀一致，地址由 aiAssistantProxy / VITE_AI_API_URL 决定",
+  '  getHeaders: () => ({',
+  '    Authorization: accessStore.accessToken ? `Bearer ${accessStore.accessToken}` : \'\',',
+  '  }),',
+  '});',
+  '',
+  'app.use(',
+  '  createAiAssistantPlugin({',
+  '    ask,',
+  '    loadPermissionInfo: async () => ({',
+  '      // 登录时已由 fetchUserInfo() 拉取并存入 accessStore，这里直接读',
+  '      menus: accessStore.accessMenus,',
+  '      permissions: accessStore.accessCodes,',
+  '    }),',
+  '    hasPermission: (code) => accessStore.accessCodes.includes(code),',
+  '    navigate: (path) => router.push(path),',
+  '  }),',
+  ');',
+].join('\n');
+
+console.log(`
+${BOLD}@hjsy/vue-ai-assistant-badge${RESET}${DIM} 安装完成，接入只差两步：${RESET}
+
+${BOLD}1. 开发代理已内置，只需指定服务地址${RESET}${DIM}（应用目录下的 vite.config.ts，如 apps/web-antdv-next/vite.config.ts）${RESET}
+${CYAN}   import { aiAssistantProxy } from '@hjsy/vue-ai-assistant-badge/vite';${RESET}
+${CYAN}   // vben 工程放进返回值的 vite.plugins；标准工程放进顶层 plugins${RESET}
+${CYAN}   vite: { plugins: [aiAssistantProxy({ target: 'http://你的AI服务地址:48080' })] }${RESET}
+${DIM}   （target 也可省略，改在 .env.development 配置 VITE_AI_API_URL；默认前缀 /v1、不 rewrite）${RESET}
+
+${BOLD}2. 注册插件${RESET}${DIM}（bootstrap.ts 通常位于应用目录的 src 下，如 apps/web-antdv-next/src/bootstrap.ts）${RESET}
+${DIM}   把下面代码粘贴到 app.use(router) 之后：${RESET}
+${bootstrapSnippet.replaceAll('\n', '\n   ')}
+
+${DIM}更完整的写法（复用宿主 requestClient / 适配层一行接入）见 docs/VBEN_INTEGRATION.md；${RESET}
+${DIM}pnpm 10+ 若未看到本提示，先执行 pnpm approve-builds 批准构建脚本。${RESET}
+`);