ai-console-hyl

一个可插拔的 Vue 3 AI 调试面板组件，支持：

• 全局 console 日志采集
• window error / unhandledrejection 异常采集
• fetch / axios 请求采集
• AI 分析面板
• 组件显示 / 隐藏控制
• 适配独立后端分析接口

适合场景：

• 给业务项目加一个调试面板
• 在测试环境快速收集前端日志和请求
• 把页面运行时数据发给 AI 做诊断分析

安装

npm install ai-console-hyl vue axios

在应用入口引入样式：

import 'ai-console-hyl/style.css'

快速开始

1. 初始化采集器

建议在应用入口初始化一次：

import axios from 'axios'
import { createApp } from 'vue'
import App from './App.vue'
import { initDevConsole } from 'ai-console-hyl'
import 'ai-console-hyl/style.css'

initDevConsole({
  axiosInstances: axios,
  analyzeEndpoint: 'https://api.haoyl2025.cn/api/ai/analyze',
})

createApp(App).mount('#app')

2. 在页面中挂载组件

<script setup lang="ts">
import { DevAIPanel } from 'ai-console-hyl'
</script>

<template>
  <DevAIPanel />
</template>

这样接入后：

• 页面日志会自动进入调试面板
• fetch / axios 请求会自动被采集
• 点击“真实AI分析当前问题”会请求你配置的后端接口

常见接入方式

方式一：最简单的默认接入

适合你自己的项目，组件自己管理显示和隐藏。

<script setup lang="ts">
import { DevAIPanel } from 'ai-console-hyl'
</script>

<template>
  <DevAIPanel />
</template>

默认行为：

• 组件会显示一个浮动入口按钮
• 点击按钮展开面板
• 面板内可手动隐藏

方式二：父组件控制显示 / 隐藏

适合你想把面板挂到某个按钮、菜单或开发模式开关上。

<script setup lang="ts">
import { ref } from 'vue'
import { DevAIPanel } from 'ai-console-hyl'

const visible = ref(false)
</script>

<template>
  <button @click="visible = !visible">切换调试面板</button>
  <DevAIPanel v-model:visible="visible" :show-toggle="false" />
</template>

方式三：作为 Vue 插件使用

import { createApp } from 'vue'
import axios from 'axios'
import App from './App.vue'
import { AiDevConsolePlugin } from 'ai-console-hyl'
import 'ai-console-hyl/style.css'

createApp(App)
  .use(AiDevConsolePlugin, {
    axiosInstances: axios,
    analyzeEndpoint: 'https://api.haoyl2025.cn/api/ai/analyze',
  })
  .mount('#app')

然后你可以在任意组件中直接使用：

<template>
  <DevAIPanel />
</template>

组件 Props

DevAIPanel 支持这些属性：

• visible?: boolean 父组件控制显示 / 隐藏
• defaultVisible?: boolean 非受控模式下默认是否展开
• showToggle?: boolean 是否显示组件自带的浮动入口按钮
• title?: string 面板标题
• closeOnBackdrop?: boolean 点击遮罩是否关闭面板
• zIndex?: number 面板层级

组件事件

• update:visible
• open
• close

示例：

<DevAIPanel
  v-model:visible="visible"
  title="项目调试面板"
  :close-on-backdrop="true"
  @open="console.log('panel opened')"
  @close="console.log('panel closed')"
/>

initDevConsole 配置项

初始化函数 initDevConsole(options) 支持这些参数：

• axiosInstances?: AxiosInstance | AxiosInstance[] 需要被采集的 axios 实例
• analyzeEndpoint?: string AI 分析接口地址
• ignoredRequestPaths?: string[] 需要从请求采集里忽略的地址
• captureLogs?: boolean 是否开启日志采集
• captureRequests?: boolean 是否开启请求采集

示例：

import axios from 'axios'
import { initDevConsole } from 'ai-console-hyl'

const request = axios.create({
  baseURL: 'https://api.example.com',
})

initDevConsole({
  axiosInstances: [axios, request],
  analyzeEndpoint: 'https://api.haoyl2025.cn/api/ai/analyze',
  ignoredRequestPaths: [
    'https://api.haoyl2025.cn/api/ai/analyze',
    'https://api.haoyl2025.cn/api/health',
  ],
})

后端接口要求

前端默认会向你配置的 analyzeEndpoint 发送 POST 请求。

请求体格式：

{
  "payload": {
    "logs": [],
    "requests": [],
    "meta": {
      "pageUrl": "https://example.com/page",
      "userAgent": "Mozilla/5.0 ...",
      "generatedAt": "2026-03-19T00:00:00.000Z"
    }
  }
}

接口返回兼容以下格式：

{
  "code": 0,
  "message": "success",
  "data": "AI分析结果文本"
}

或者：

{
  "analysis": "AI分析结果文本"
}

或者：

{
  "data": {
    "analysis": "AI分析结果文本"
  }
}

接入真实线上接口

如果你已经有可访问的线上服务，例如：

https://api.haoyl2025.cn/api/ai/analyze

那就在初始化时这样写：

initDevConsole({
  axiosInstances: axios,
  analyzeEndpoint: 'https://api.haoyl2025.cn/api/ai/analyze',
})

如果你的前端是本地开发环境，比如：

http://localhost:5173

后端需要允许这个来源跨域访问，例如：

CORS_ORIGIN=http://localhost:5173,http://127.0.0.1:5173,https://你的正式域名

在别的项目里怎么接

最推荐的接法就是两步：

第一步：入口初始化

import axios from 'axios'
import { initDevConsole } from 'ai-console-hyl'
import 'ai-console-hyl/style.css'

initDevConsole({
  axiosInstances: axios,
  analyzeEndpoint: 'https://api.haoyl2025.cn/api/ai/analyze',
})

第二步：任意页面挂组件

<script setup lang="ts">
import { DevAIPanel } from 'ai-console-hyl'
</script>

<template>
  <DevAIPanel />
</template>

常见问题

1. 面板能显示，但没有请求记录

常见原因：

• 你项目里用了 axios.create()，但没有把实例传给 initDevConsole
• 请求在初始化前就发出了
• 请求被你主动配置为忽略路径

正确示例：

const request = axios.create()

initDevConsole({
  axiosInstances: [axios, request],
})

2. 点击 AI 分析时报 Failed to fetch

通常是以下问题：

• 后端地址写错
• 后端没启动
• HTTPS 证书有问题
• 跨域没放行

先检查：

curl https://api.haoyl2025.cn/api/health

3. 浏览器里请求报 CORS 错误

说明后端没放行当前前端域名。

例如你本地开发时，后端需要允许：

CORS_ORIGIN=http://localhost:5173,http://127.0.0.1:5173

4. 为什么面板自己的分析接口没有出现在请求列表里

这是组件的默认行为。

为了避免“面板自己的请求”污染业务请求视图，分析接口和健康检查接口默认会被忽略。

本地开发

运行 demo：

npm install
npm run dev

构建 npm 包：

npm run build

检查发布内容：

npm run pack:check

发布 npm 包

发布前建议检查：

1. package.json 中的 name 是否可用
2. version 是否已更新
3. 是否已执行 npm run build
4. 是否已执行 npm run pack:check
5. npm 账号是否具备发布权限

发布命令：

npm publish