Ask AI Widget - Build Instructions#

📁 项目结构#

docs/sphinx_doc/source/_static/
├── ask-ai-modules/              # 模块化源代码
│   ├── ask-ai-i18n.js          # 国际化配置
│   ├── ask-ai-api.js           # API 通信层
│   ├── ask-ai-ui.js            # UI 渲染和交互
│   └── ask-ai-widget.js        # 主控制器
├── ask-ai-widget.js            # 打包后的单文件（用于生产）
├── ask-ai-widget.js.backup     # 原始文件备份
├── package.json                # Node.js 依赖配置
├── rollup.config.js            # Rollup 打包配置
└── BUILD.md                    # 本文档

🚀 快速开始#

1. 安装依赖#

在 docs/sphinx_doc/source/_static/ 目录下运行：

npm install

2. 构建打包文件#

npm run build

这将会：

  • 读取 ask-ai-modules/ 目录下的所有模块

  • 使用 Rollup 将它们打包成单个文件

  • 输出到 ask-ai-widget.js（覆盖原文件）

3. 开发模式（监听文件变化）#

npm run watch

在开发模式下，任何对 ask-ai-modules/ 中文件的修改都会自动触发重新打包。

📝 模块说明#

ask-ai-i18n.js#

  • 功能：国际化配置

  • 导出：I18N 对象和 detectLanguage() 函数

  • 大小：约 2KB

ask-ai-api.js#

  • 功能：API 通信层

  • 导出：AskAIApi 类

  • 职责：

    • API 连接检查

    • 会话历史加载

    • 流式响应处理

    • 会话清除

  • 大小：约 8KB

ask-ai-ui.js#

  • 功能：UI 渲染和交互

  • 导出：AskAIUI 类

  • 职责：

    • DOM 创建和管理

    • 事件绑定

    • 消息渲染

    • 主题切换

    • Markdown 渲染

  • 大小：约 12KB

ask-ai-widget.js#

  • 功能：主控制器

  • 导出：AskAIWidget 类（默认导出）

  • 职责：

    • 整合所有模块

    • 初始化流程

    • 业务逻辑协调

  • 大小：约 4KB

🔧 修改代码#

修改流程#

  1. 编辑模块文件：在 ask-ai-modules/ 目录下修改对应的模块

  2. 重新构建：运行 npm run build

  3. 测试：在浏览器中测试打包后的文件

添加新功能#

如果需要添加新功能：

  1. 确定功能属于哪个模块（I18N、API、UI 或主控制器）

  2. 在对应模块中添加代码

  3. 如果需要跨模块调用，通过导出/导入机制实现

  4. 重新构建并测试

📦 打包说明#

打包配置说明#

rollup.config.js 配置：

{
  input: 'ask-ai-modules/ask-ai-widget.js',  // 入口文件
  output: {
    file: 'ask-ai-widget.js',                 // 输出文件
    format: 'iife',                           // 立即执行函数格式
    name: 'AskAIWidget',                      // 全局变量名
    globals: { marked: 'marked' }             // 外部依赖映射
  },
  external: ['marked']                        // 不打包 marked 库
}

🔍 故障排查#

构建失败#

如果构建失败，检查：

  1. Node.js 版本是否 >= 14

  2. 依赖是否正确安装（npm install）

  3. 模块文件中是否有语法错误

功能异常#

如果打包后功能异常：

  1. 检查浏览器控制台错误

  2. 确认 marked.js 已正确加载

📚 相关文档#