Jan扩展开发API文档：从入门到精通-优快云博客

Jan扩展开发API文档：从入门到精通

【免费下载链接】jan Jan 是一个开源的 ChatGPT 替代品，它完全在您的电脑上离线运行。项目地址: https://gitcode.com/GitHub_Trending/ja/jan

Jan是一个开源的本地AI应用平台，完全在本地离线运行。扩展系统是Jan的核心功能之一，允许开发者通过模块化方式扩展其能力。本文档将系统介绍Jan扩展开发的完整流程，从环境搭建到API使用，帮助开发者快速掌握扩展开发技能。

扩展开发基础

什么是Jan扩展

Jan扩展是自包含的功能模块，可添加特定功能到Jan应用。扩展采用模块化设计，允许开发者灵活扩展Jan的能力，如添加新的AI模型支持、实现自定义对话逻辑或集成外部服务。当前项目中已包含多种类型的扩展，如assistant-extension（助手CRUD操作）、conversational-extension（对话状态管理）和llamacpp-extension（本地模型推理）等。

扩展类型

Jan定义了多种扩展类型，每种类型对应不同的功能领域：

export enum ExtensionTypeEnum {
  Assistant = 'assistant',         // 助手功能扩展
  Conversational = 'conversational', // 对话功能扩展
  Inference = 'inference',         // 推理引擎扩展
  Model = 'model',                 // 模型支持扩展
  SystemMonitoring = 'systemMonitoring', // 系统监控扩展
  MCP = 'mcp',                     // MCP协议扩展
  HuggingFace = 'huggingFace',     // HuggingFace集成扩展
  Engine = 'engine',               // 引擎扩展
  Hardware = 'hardware'            // 硬件支持扩展
}

开发者可根据功能需求选择合适的扩展类型，完整定义见core/src/browser/extension.ts。

开发环境搭建

准备工作

开始扩展开发前，需确保本地环境已安装：

Node.js (v16+) 和 npm/yarn
Git
代码编辑器（推荐VS Code）

获取源代码

git clone https://gitcode.com/GitHub_Trending/ja/jan.git
cd jan

扩展项目初始化

创建新扩展的基本步骤：

# 创建扩展目录
mkdir -p extensions/my-first-extension
cd extensions/my-first-extension

# 初始化项目
yarn init -y

# 安装核心依赖
yarn add @janhq/core

扩展结构解析

标准扩展结构

Jan扩展遵循统一的目录结构，确保一致性和可维护性：

my-first-extension/
├── package.json          # 扩展元数据和依赖
├── rolldown.config.mjs   # 构建配置
├── src/
│   └── index.ts          # 扩展入口点
└── settings.json         # 扩展设置（可选）

package.json 配置

扩展的package.json需要包含特定字段：

{
  "name": "@janhq/my-first-extension",
  "version": "0.1.0",
  "main": "dist/index.js",
  "keywords": ["jan", "extension"],
  "jan": {
    "type": "conversational",
    "compatibility": {
      "platform": ["win32", "darwin", "linux"],
      "version": ">=0.4.0"
    }
  }
}

入口文件 (index.ts)

扩展入口文件需导出一个继承自BaseExtension的类：

import { Extension } from '@janhq/core'

export default class MyFirstExtension extends Extension {
  async onLoad() {
    // 扩展初始化逻辑
    console.log('My first extension loaded!')
    
    // 注册服务示例
    this.registerService('greetingService', {
      sayHello: async (name: string) => `Hello, ${name}!`
    })
  }
  
  async onUnload() {
    // 清理逻辑
    console.log('My first extension unloaded!')
  }
  
  type() {
    return 'conversational'; // 指定扩展类型
  }
}

核心API参考

扩展生命周期

Jan扩展具有明确的生命周期，通过重写相应方法实现自定义逻辑：

onLoad()

当扩展被加载时调用，用于初始化资源、注册服务和事件监听：

async onLoad() {
  // 注册模型
  await this.registerModels([{
    id: 'my-custom-model',
    name: 'My Custom Model',
    provider: 'my-extension',
    description: 'A custom model provided by my extension'
  }]);
  
  // 监听事件
  this.on('model:loaded', (model) => {
    console.log(`Model ${model.id} loaded`);
  });
}

onUnload()

当扩展被卸载时调用，用于清理资源、移除事件监听：

async onUnload() {
  // 移除事件监听
  this.off('model:loaded');
  
  // 清理其他资源
}

服务注册

扩展可以注册服务供其他扩展或应用核心调用：

// 注册服务
this.registerService('calculator', {
  add: async (a: number, b: number) => a + b,
  multiply: async (a: number, b: number) => a * b
});

// 调用其他服务
const result = await this.callService('calculator', 'add', 2, 3);
console.log(result); // 输出: 5

事件系统

Jan提供事件系统实现扩展间通信，支持自定义事件和系统事件：

系统事件

系统预定义了多种事件，完整列表见core/src/types/api/index.ts：

// 监听模型加载事件
this.on('model:loaded', (model) => {
  console.log(`Model loaded: ${model.id}`);
});

// 监听下载进度事件
this.on('onFileDownloadUpdate', (progress) => {
  console.log(`Download progress: ${progress.percent}%`);
});

自定义事件

扩展可以发射自定义事件供其他扩展监听：

// 发射自定义事件
this.emit('my-extension:data-updated', { timestamp: Date.now(), data: {} });

// 监听自定义事件
this.on('my-extension:data-updated', (data) => {
  console.log('Received updated data:', data);
});

设置管理

扩展可以注册和管理自定义设置，与Jan的设置界面集成：

async onLoad() {
  // 注册设置
  await this.registerSettings([
    {
      key: 'greetingLanguage',
      name: 'Greeting Language',
      description: 'Language for greetings',
      controllerProps: {
        type: 'dropdown',
        value: 'en',
        options: [
          { label: 'English', value: 'en' },
          { label: 'Spanish', value: 'es' },
          { label: 'French', value: 'fr' }
        ]
      }
    }
  ]);
  
  // 读取设置
  const lang = await this.getSetting('greetingLanguage', 'en');
  console.log(`Current greeting language: ${lang}`);
}

高级功能

模型集成

扩展可以集成新的AI模型，通过实现Inference类型扩展：

import { Extension, InferenceExtension } from '@janhq/core'

export default class CustomModelExtension extends Extension implements InferenceExtension {
  async generateCompletion(params) {
    // 实现推理逻辑
    const { messages, model, stream } = params;
    
    // 调用模型并返回结果
    return {
      id: 'completion-123',
      object: 'text_completion',
      created: Date.now(),
      model: model,
      choices: [{
        index: 0,
        text: 'This is a custom model response'
      }]
    };
  }
  
  type() {
    return 'inference';
  }
}

UI组件扩展

扩展可以提供自定义UI组件，集成到Jan应用界面：

async onLoad() {
  // 注册设置页面组件
  this.registerUIComponent('settings-page', {
    component: () => import('./components/SettingsPage'),
    title: 'My Extension Settings',
    icon: 'settings'
  });
}

测试与调试

本地测试

# 构建扩展
yarn build

# 链接到Jan应用
ln -s ./extensions/my-first-extension ~/.jan/extensions/

# 启动Jan应用
yarn start

调试技巧

查看扩展加载状态：

// 在Jan开发者控制台中
console.log(window.core.extensions);

事件调试：

// 在扩展中监听所有事件
this.on('*', (event, data) => {
  console.log(`Event: ${event}`, data);
});

常见问题排查：

扩展未加载：检查package.json格式和扩展类型定义
事件不触发：确保在onLoad()中注册事件监听
服务不可用：确认服务注册名称和调用方式

打包与分发

构建扩展

# 安装构建工具（如未安装）
yarn add -D rolldown typescript

# 执行构建
yarn build

打包扩展

# 创建扩展包
zip -r my-first-extension.zip dist package.json settings.json

扩展包可提交到Jan扩展市场或在本地安装：

# 本地安装扩展
jan extension install ./my-first-extension.zip

最佳实践

代码组织

保持扩展功能单一专注
使用TypeScript确保类型安全
模块化设计，分离关注点

性能优化

延迟加载非关键资源
避免阻塞主线程的同步操作
合理使用缓存减少重复计算

错误处理

async onLoad() {
  try {
    // 可能出错的操作
    await this.initializeCriticalResources();
  } catch (error) {
    console.error('Failed to initialize extension:', error);
    // 显示用户友好错误
    this.showToast('Extension initialization failed', 'error');
  }
}

兼容性考虑

compatibility() {
  return {
    platform: ['win32', 'darwin', 'linux'],
    version: '>=0.4.0'
  };
}

示例扩展

事件监听示例

THE 0TH POSITION OF THE ORIGINAL IMAGE

以下是监听模型下载事件的扩展示例：

import { Extension } from '@janhq/core'

export default class DownloadMonitorExtension extends Extension {
  async onLoad() {
    console.log('Download monitor extension loaded');
    
    // 监听下载事件
    this.on('onFileDownloadUpdate', (progress) => {
      console.log(`Download progress: ${progress.percent}%`);
      // 更新UI或执行其他逻辑
    });
    
    this.on('onFileDownloadSuccess', (file) => {
      console.log(`File downloaded successfully: ${file.path}`);
      // 下载完成后处理
    });
  }
  
  async onUnload() {
    console.log('Download monitor extension unloaded');
  }
  
  type() {
    return 'systemMonitoring';
  }
}

完整示例扩展

查看项目中的示例扩展：

对话扩展：实现对话管理功能
下载扩展：处理模型下载逻辑
Llama.cpp扩展：本地模型推理实现

资源与参考

官方文档

社区资源

Jan开发者社区：通过Discord加入讨论
GitHub Issues：提交问题和功能请求
示例扩展库：查看社区贡献的扩展示例

开发工具

Jan CLI：扩展开发命令行工具
TypeScript类型定义：提供完整的类型支持
调试工具：自动化测试和调试脚本

通过本文档，您应该已经掌握了Jan扩展开发的基础知识和API使用方法。开始创建您的第一个扩展，为Jan添加强大的新功能吧！

【免费下载链接】jan Jan 是一个开源的 ChatGPT 替代品，它完全在您的电脑上离线运行。项目地址: https://gitcode.com/GitHub_Trending/ja/jan

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考