Knowledge Models 打包脚本

specflow-knowledge-models 的构建和打包工具

📦 功能特性

这个打包脚本提供了以下功能：

• ✅ 复制模型文件 — 将 models/ 目录复制到 dist/models/
• ✅ 生成入口文件 — 创建 ESM 和 CJS 格式的入口文件
• ✅ 类型声明 — 自动生成 TypeScript 类型声明文件
• ✅ 增量构建 — 只复制变更的文件，提升构建速度
• ✅ 清理构建 — 支持清理旧构建后重新构建
• ✅ 彩色输出 — 清晰的构建日志输出

🚀 使用方法

基本构建

cd packages/knowledge-models
npm run build

这会执行 node scripts/build.js，完成完整的构建流程。

增量构建

npm run build:incremental
# 或
node scripts/build.js --incremental

增量构建只会复制自上次构建后变更的文件，大幅提升构建速度。

清理后重新构建

npm run build:clean
# 或
node scripts/build.js --clean

会先删除 dist/ 目录，然后重新构建。

清理构建产物

npm run clean

删除 dist/ 目录。

📁 构建输出

构建成功后会生成 dist/ 目录：

dist/
├── index.cjs              # CJS 格式入口文件
├── index.mjs              # ESM 格式入口文件
├── index.d.ts             # TypeScript 类型声明
├── package.json           # 复制的 package.json（用于发布）
└── models/               # 模型文件目录
    └── BAAI/
        └── bge-base-zh-v1.5/
            ├── config.json
            ├── model_quantized.onnx
            ├── special_tokens_map.json
            ├── tokenizer.json
            ├── tokenizer_config.json
            └── vocab.txt

🔧 API 说明

入口文件导出的函数

getModelPath()

获取模型文件的根目录路径。

// CJS
const { getModelPath } = require("specflow-knowledge-models");
console.log(getModelPath());
// 输出: /path/to/node_modules/specflow-knowledge-models/dist/models

// ESM
import { getModelPath } from "specflow-knowledge-models";
console.log(getModelPath());

getModelPathByName(modelName)

获取指定模型的路径。

const { getModelPathByName } = require("specflow-knowledge-models");
console.log(getModelPathByName("BAAI/bge-base-zh-v1.5"));
// 输出: /path/to/node_modules/.../models/BAAI/bge-base-zh-v1.5

listModels()

列出所有可用的模型。

const { listModels } = require("specflow-knowledge-models");
console.log(listModels());
// 输出: ['BAAI']

🛠️ 脚本选项

命令行参数

node scripts/build.js [选项]

选项：

• -i, --incremental — 增量构建（只复制变更的文件）
• -c, --clean — 清理旧构建后重新构建
• -h, --help — 显示帮助信息

示例：

# 完整构建
node scripts/build.js

# 增量构建
node scripts/build.js --incremental

# 清理后重新构建
node scripts/build.js --clean

# 显示帮助
node scripts/build.js --help

📝 构建流程

脚本的执行流程：

1. 解析命令行参数 — 支持 --incremental、--clean、--help
2. 清理旧构建（如果指定了 --clean）
3. 复制模型文件 — 递归复制 models/ 到 dist/models/
4. 生成 CJS 入口文件 — 创建 dist/index.cjs
5. 生成 ESM 入口文件 — 创建 dist/index.mjs
6. 生成类型声明文件 — 创建 dist/index.d.ts
7. 复制 package.json — 复制一份到 dist/（用于发布）

🐛 故障排查

问题 1：模型文件复制失败

原因：models/ 目录不存在或权限不足

解决：

# 检查 models/ 目录是否存在
ls -la packages/knowledge-models/models/

# 检查权限
chmod -R 755 packages/knowledge-models/models/

问题 2：构建输出不完整

原因：构建过程被中断

解决：

# 清理后重新构建
npm run build:clean

问题 3：增量构建不生效

原因：文件时间戳未正确更新

解决：

# 使用清理构建
npm run build:clean

🔄 与旧脚本对比

旧脚本（内联命令）

{
  "build": "node -e \"const fs=require('fs');...\""
}

缺点：

• ❌ 难以维护和阅读
• ❌ 不支持增量构建
• ❌ 错误信息不清晰
• ❌ 无法添加新功能

新脚本（独立文件）

{
  "build": "node scripts/build.js"
}

优点：

• ✅ 清晰易读，易于维护
• ✅ 支持增量构建
• ✅ 彩色日志输出
• ✅ 易于扩展新功能
• ✅ 支持命令行参数

📚 相关文档

• Knowledge Engine 文档
• Rollify 配置指南

🎉 总结

现在 knowledge-models 包有了一个功能完善、易于维护的打包脚本！

快速开始：

cd packages/knowledge-models
npm run build

查看构建输出：

ls -la dist/

祝构建顺利！🚀