指南：用 TypeScript 構(gòu)建、打包并測試你自己的 Jan 擴展)
Jan Assistant 擴展開發(fā)指南用 TypeScript 構(gòu)建、打包并測試你自己的 Jan 擴展【免費下載鏈接】janJan is an open source alternative to ChatGPT that runs 100% offline on your computer.項目地址: https://gitcode.com/GitHub_Trending/ja/jan本文以 Jan 倉庫中的 assistant-extension 模板 為核心結(jié)合 core 包中的擴展基類、擴展源碼 與 單元測試完整講解如何用 TypeScript 創(chuàng)建、打包、安裝和演進一個 Jan 擴展從package.json元數(shù)據(jù)定義、rolldown 構(gòu)建產(chǎn)物到file://虛擬文件系統(tǒng)中的助手數(shù)據(jù)遷移機制讀者可據(jù)此獨立開發(fā)自己的 Jan 擴展。一、模板定位assistant-extension 在 Jan 倉庫中的角色Jan 是運行在本地的開源 AI 聊天應(yīng)用其功能通過“擴展Extension”機制進行模塊化拆分助手管理、對話編排、推理后端、模型下載、RAG、向量庫等能力都實現(xiàn)為獨立擴展由janhq/core包提供統(tǒng)一的事件、文件系統(tǒng)和類型系統(tǒng)。extensions/assistant-extension 目錄既是 Jan 內(nèi)置的默認 AI 助手實現(xiàn)也被官方 README 明確定位為一個可直接 fork 使用的擴展腳手架模板。README 開篇即說明Use this template to bootstrap the creation of a TypeScript Jan extension.因此圍繞該目錄學習既能掌握“如何寫一個新擴展”又能順帶讀懂 Jan 默認助手默認系統(tǒng)提示詞、默認采樣參數(shù)、助手持久化與數(shù)據(jù)遷移的完整實現(xiàn)。二、創(chuàng)建你自己的擴展模板使用與初始環(huán)境搭建README 給出了標準的模板使用流程點擊倉庫頂部的 Use this template 按鈕選擇 Create a new repository為新的倉庫選擇 owner 與名稱點擊 Create repository克隆你的新倉庫到本地。環(huán)境要求模板 README 明確要求一個較新的 Node.js 環(huán)境20.x 或更高版本如果在使用nodenv/nvm這類版本管理器可以在倉庫根目錄按package.json中指定的版本安裝對應(yīng) Node。需要說明的一個倉庫事實是當前 package.json 中聲明了packageManager: yarn4.5.3且依賴使用了workspace:*協(xié)議janhq/core: workspace:*這意味著在 Jan monorepo 內(nèi)部開發(fā)時應(yīng)使用 Yarn 4 工作區(qū)而在 fork 出的獨立模板倉庫中按 README 使用npm install同樣可行獨立倉庫中janhq/core會解析為 npm 發(fā)布版本。依賴安裝、打包與產(chǎn)物檢查README 描述的三步工作流以及當前倉庫中對應(yīng)的真實腳本# 1. 安裝依賴 npm install # 2. 打包 TypeScriptREADME 中的命令當前倉庫腳本名為 build npm run bundle # 對應(yīng)當前 package.json 中的 build: rolldown -c rolldown.config.mjs # 3. 檢查產(chǎn)物擴展目錄中會出現(xiàn) .tgz 文件對照當前 package.json 的scripts可確認模板命令與倉庫實際腳本的對應(yīng)關(guān)系{ build: rolldown -c rolldown.config.mjs, build:publish: rimraf *.tgz --glob || true yarn build npm pack cpx *.tgz ../../pre-install, test: vitest run }即build完成 rolldown 打包build:publish在清理舊產(chǎn)物后執(zhí)行build再用npm pack生成.tgz安裝包并復制到倉庫的pre-install目錄隨 Jan 應(yīng)用預裝test運行 vitest 測試。README 中提到的 “tgz 產(chǎn)物”即由npm pack產(chǎn)生。三、擴展元數(shù)據(jù)package.json 字段逐項解讀README 指出package.json定義了擴展的名稱、主入口、描述和版本等元數(shù)據(jù)fork 模板后必須更新其中的name與description。以當前模板文件為參照各關(guān)鍵字段含義如下字段當前值作用namejanhq/assistant-extension擴展包名是 Jan 識別擴展的唯一標識productNameJan Assistant展示在產(chǎn)品界面中的名稱version1.0.2擴展版本號maindist/index.js擴展主入口打包產(chǎn)物路徑nodedist/node/index.js節(jié)點側(cè)入口如存在獨立后端邏輯author/licenseJan servicejan.ai/AGPL-3.0作者與協(xié)議信息dependenciesjanhq/core唯一運行時依賴Jan 擴展核心包filesdist/*,package.json,README.md發(fā)布進.tgz包的文件白名單installConfig.hoistingLimitsworkspaces在 monorepo 中避免依賴被提升hoisting到工作區(qū)外這些字段并非擺設(shè)rolldown 構(gòu)建配置會直接讀取它們見下一節(jié)core 包的BaseExtension構(gòu)造參數(shù)name / productName / url / active / description / version見 extension.ts也與元數(shù)據(jù)一一對應(yīng)。四、構(gòu)建管線從 src/index.ts 到 dist/index.jsrolldown.config.mjs 完整展示了擴展的打包邏輯值得逐行理解import { defineConfig } from rolldown import pkgJson from ./package.json with { type: json } export default defineConfig([ { input: src/index.ts, output: { format: esm, file: dist/index.js, // 即 package.json 中的 main 字段 }, platform: browser, define: { NODE: JSON.stringify(${pkgJson.name}/${pkgJson.node}), VERSION: JSON.stringify(pkgJson.version), }, } ])要點入口是src/index.ts輸出為ESM 格式單文件dist/index.js正好落在package.json的main聲明位置platform: browser表明擴展代碼運行在瀏覽器/前端運行時環(huán)境中define在編譯期注入了兩個全局常量NODE與VERSION其值來自package.json的name/node/version字段。這與 src/types/global.d.ts 中的聲明相呼應(yīng)declare const NODE: string declare const VERSION: string也就是說擴展代碼在運行時可以直接讀取自身的包名與版本號無需額外配置。tsconfig.json 則規(guī)定了編譯口徑target: es2016、module: ES6、declaration: true聲明文件輸出到dist/types、sourceMap: true與 ESM 打包目標保持一致。五、擴展代碼骨架繼承 AssistantExtension 與生命周期模板 README 對擴展代碼有兩點核心提示大部分 Jan 擴展函數(shù)都是異步處理的擴展函數(shù)會返回Promiseany事件訂閱的典型寫法如下摘自 READMEimport { events, MessageEvent, MessageRequest } from janhq/core function onStart(): Promiseany { return events.on(MessageEvent.OnMessageSent, (data: MessageRequest) this.inference(data) ) }在 core 包中擴展體系以抽象類層次組織BaseExtension所有擴展的基類定義了name、url、active、description、version等屬性以及兩個必須實現(xiàn)的生命周期鉤子onLoad()/onUnload()還提供了registerModels、registerSettings等通用能力AssistantExtension助手類型擴展的抽象中間層聲明type()返回ExtensionTypeEnum.Assistant并要求實現(xiàn)三個抽象方法export abstract class AssistantExtension extends BaseExtension implements AssistantInterface { type(): ExtensionTypeEnum | undefined { return ExtensionTypeEnum.Assistant } abstract createAssistant(assistant: Assistant): Promisevoid abstract deleteAssistant(assistant: Assistant): Promisevoid abstract getAssistants(): PromiseAssistant[] }Assistant的數(shù)據(jù)形狀定義在 core/src/types/assistant/assistantEntity.ts包含avatar、id、object、created_at、name、description、model、instructions、tools、file_ids、metadata等字段并配有逐字段注釋是編寫助手相關(guān)擴展時最核心的類型契約。模板 README 指向的 Jan Extension Core 模塊文檔在本倉庫中即 core/README.md。六、默認助手實現(xiàn)解析onLoad、持久化與種子數(shù)據(jù)extensions/assistant-extension/src/index.ts 中的JanAssistantExtension是模板的參考實現(xiàn)onLoad()L17-L39展示了擴展加載時應(yīng)當完成的標準初始化序列async onLoad() { if (!(await fs.existsSync(file://assistants))) { await fs.mkdir(file://assistants) } // Run migrations if needed await this.runMigrations() const assistants await this.readAssistantsFromDisk() if (assistants.length 0) { const assistantWithParams { ...this.defaultAssistant, parameters: { temperature: 0.7, top_k: 20, top_p: 0.8, repeat_penalty: 1.12, }, } await this.createAssistant(assistantWithParams as Assistant) } }這里體現(xiàn)了 Jan 擴展編程模型的三個關(guān)鍵特征虛擬文件系統(tǒng)一切持久化都通過file://前綴路徑進行如file://assistants、file://assistants/id/assistant.json由janhq/core導出的fs模塊統(tǒng)一抽象屏蔽了不同平臺的真實磁盤差異。這是一個寫自定義擴展時必須記住的約定——不要直接使用 Node 的fs模塊。冪等初始化先確保目錄存在再執(zhí)行遷移最后僅在磁盤為空時寫入種子數(shù)據(jù)避免覆蓋用戶已自定義的助手對應(yīng)測試用例 “does not overwrite an existing persisted assistant on load”。種子參數(shù)默認助手Janid: jan、avatar: 、model: *表示適配所有已安裝模型附帶默認采樣參數(shù)temperature: 0.7 / top_k: 20 / top_p: 0.8 / repeat_penalty: 1.12其instructions是一段要求“按用戶語言回復、逐步推理、作為專業(yè)工具調(diào)用者分析信息缺口”的系統(tǒng)提示詞并帶有{{current_date}}日期占位符tools中默認掛了一個禁用狀態(tài)的retrieval工具附帶top_k: 2、chunk_size: 1024、chunk_overlap: 64的 RAG 檢索配置與檢索提示詞模板L333-L351。CRUD 方法本身也非常短小是“最小可運行擴展”的范例createAssistantL281-L292確保file://assistants/id/目錄存在后把助手序列化為縮進 JSON 寫入assistant.jsondeleteAssistantL294-L303存在即刪除assistant.json不存在則為空操作no-opgetAssistantsL275-L279優(yōu)先讀取磁盤數(shù)據(jù)磁盤為空時回退到內(nèi)置的defaultAssistant保證上層調(diào)用總能拿到至少一個可用助手。私有方法readAssistantsFromDisk還會跳過缺少assistant.json的目錄以及 JSON 解析失敗的損壞文件只記錄錯誤而不中斷整體加載。七、數(shù)據(jù)遷移機制版本化 .migration_version 與三級遷移JanAssistantExtension內(nèi)置了一套值得借鑒的輕量數(shù)據(jù)遷移方案L41-L95遷移版本記錄在file://assistants/.migration_version文件中當前版本常量CURRENT_MIGRATION_VERSION 3getCurrentMigrationVersion()讀取該文件文件缺失或內(nèi)容無法解析parseInt得到NaN時一律按版本 0處理從而保證遷移一定會補跑runMigrations()按currentVersion N的條件逐檔執(zhí)行遷移每完成一檔立即寫回版本號版本遷移內(nèi)容v1將舊版指令前綴You are a helpful AI assistant.改寫為You are Jan, a helpful AI assistant.并保留后續(xù)自定義內(nèi)容用startsWith 字符串截取實現(xiàn)v2將舊前綴助手整體改寫為新版默認指令含工具調(diào)用分析流程、{{current_date}}占位符并補齊默認采樣參數(shù)v3僅當助手指令與 v2 寫入的默認文本逐字完全一致時剝離身份前綴段落恢復為純默認指令用戶自定義提示詞不受影響遷移邏輯刻意保守每一檔都先做字符串精確匹配再改寫且失敗時只logger.error而不拋出確保單個助手損壞不會阻塞整個擴展啟動。這種“版本號文件 條件式補跑 精確匹配保護用戶數(shù)據(jù)”的模式可直接移植到任何需要持久化狀態(tài)演進的 Jan 擴展中。八、測試實踐用內(nèi)存文件系統(tǒng)驗證擴展邏輯模板自帶 src/index.test.ts展示了官方推薦的擴展測試方式用 vitest 對janhq/core的fs進行 mock以兩個內(nèi)存容器模擬虛擬文件系統(tǒng)——let files: Mapstring, string // 路徑 - 文件內(nèi)容 let dirs: Setstring // 已存在的目錄existsSync / mkdir / writeFileSync / readFileSync / rm / readdirSync全部落到Map/Set上L12-L45使得測試完全不依賴真實磁盤。測試覆蓋的斷言點恰好對應(yīng)第六、七節(jié)的所有行為getAssistants目錄不存在、目錄為空時均回退默認助手id: jan能并行讀取多個助手跳過無assistant.json的孤兒目錄與 JSON 損壞的條目createAssistant自動建目錄并寫入格式化 JSON斷言輸出含\n縮進目錄已存在時不再調(diào)用mkdirdeleteAssistant存在時刪除文件不存在時fs.rm根本不被調(diào)用onLoad自動創(chuàng)建file://assistants目錄、寫入遷移版本3、種子助手攜帶正確的默認參數(shù)、且不覆蓋已持久化的自定義助手遷移v1 精確替換前綴且保留尾部自定義文本You are a helpful AI assistant. Be concise.→You are Jan, a helpful AI assistant. Be concise.v2 寫入?yún)?shù)、v3 剝掉身份前綴已經(jīng)是版本 3 時不重復執(zhí)行遷移版本文件內(nèi)容為garbage時按 0 處理并補跑。運行方式即npm test對應(yīng)test: vitest run測試環(huán)境由 vitest.config.ts 與 src/test/setup.ts 配置。九、動手清單從模板到自定義擴展綜合 README 與源碼把模板改造為自己的擴展可以按以下清單執(zhí)行改名與元數(shù)據(jù)更新 package.json 的name、productName、description、author并提升version替換源碼src/是擴展的心臟README 明確允許整體替換。自定義擴展類應(yīng)繼承 core 中與你目標能力對應(yīng)的抽象基類如AssistantExtension實現(xiàn)其全部抽象方法并在onLoad()中完成初始化、onUnload()中做清理遵循異步約定所有擴展函數(shù)按異步風格編寫返回Promise需要響應(yīng)消息等應(yīng)用事件時使用janhq/core的events.on(...)訂閱持久化走 file:// 協(xié)議使用 core 導出的fs與joinPath管理數(shù)據(jù)目錄避免直接操作宿主磁盤構(gòu)建與驗證執(zhí)行npm install后運行build即 README 所述的打包步驟確認dist/index.js生成用npm pack或倉庫內(nèi)的build:publish生成.tgz產(chǎn)物回歸測試參照 src/index.test.ts 的內(nèi)存 fs mock 手法為你的存儲與遷移邏輯補測試再執(zhí)行npm test。以上流程均以當前倉庫的實際文件為準模板文檔見 extensions/assistant-extension/README.md構(gòu)建與類型配置見 rolldown.config.mjs、tsconfig.json擴展契約見 core/src/browser/extension.ts 與 core/src/browser/extensions/assistant.ts助手類型契約見 core/src/types/assistant/assistantEntity.ts。掌握這套“元數(shù)據(jù) 打包 生命周期 虛擬文件系統(tǒng)持久化 版本化遷移”的組合模式即可在 Jan 生態(tài)中開發(fā)并分發(fā)自己的功能擴展?！久赓M下載鏈接】janJan is an open source alternative to ChatGPT that runs 100% offline on your computer.項目地址: https://gitcode.com/GitHub_Trending/ja/jan創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Jan Assistant 擴展開發(fā)指南：用 TypeScript 構(gòu)建、打包并測試你自己的 Jan 擴展
Jan Assistant 擴展開發(fā)指南用 TypeScript 構(gòu)建、打包并測試你自己的 Jan 擴展【免費下載鏈接】janJan is an open source alternative to ChatGPT that runs 100% offline on your computer.項目地址: https://gitcode.com/GitHub_Trending/ja/jan本文以 Jan 倉庫中的 assistant-extension 模板 為核心結(jié)合 core 包中的擴展基類、擴展源碼 與 單元測試完整講解如何用 TypeScript 創(chuàng)建、打包、安裝和演進一個 Jan 擴展從package.json元數(shù)據(jù)定義、rolldown 構(gòu)建產(chǎn)物到file://虛擬文件系統(tǒng)中的助手數(shù)據(jù)遷移機制讀者可據(jù)此獨立開發(fā)自己的 Jan 擴展。一、模板定位assistant-extension 在 Jan 倉庫中的角色Jan 是運行在本地的開源 AI 聊天應(yīng)用其功能通過“擴展Extension”機制進行模塊化拆分助手管理、對話編排、推理后端、模型下載、RAG、向量庫等能力都實現(xiàn)為獨立擴展由janhq/core包提供統(tǒng)一的事件、文件系統(tǒng)和類型系統(tǒng)。extensions/assistant-extension 目錄既是 Jan 內(nèi)置的默認 AI 助手實現(xiàn)也被官方 README 明確定位為一個可直接 fork 使用的擴展腳手架模板。README 開篇即說明Use this template to bootstrap the creation of a TypeScript Jan extension.因此圍繞該目錄學習既能掌握“如何寫一個新擴展”又能順帶讀懂 Jan 默認助手默認系統(tǒng)提示詞、默認采樣參數(shù)、助手持久化與數(shù)據(jù)遷移的完整實現(xiàn)。二、創(chuàng)建你自己的擴展模板使用與初始環(huán)境搭建README 給出了標準的模板使用流程點擊倉庫頂部的 Use this template 按鈕選擇 Create a new repository為新的倉庫選擇 owner 與名稱點擊 Create repository克隆你的新倉庫到本地。環(huán)境要求模板 README 明確要求一個較新的 Node.js 環(huán)境20.x 或更高版本如果在使用nodenv/nvm這類版本管理器可以在倉庫根目錄按package.json中指定的版本安裝對應(yīng) Node。需要說明的一個倉庫事實是當前 package.json 中聲明了packageManager: yarn4.5.3且依賴使用了workspace:*協(xié)議janhq/core: workspace:*這意味著在 Jan monorepo 內(nèi)部開發(fā)時應(yīng)使用 Yarn 4 工作區(qū)而在 fork 出的獨立模板倉庫中按 README 使用npm install同樣可行獨立倉庫中janhq/core會解析為 npm 發(fā)布版本。依賴安裝、打包與產(chǎn)物檢查README 描述的三步工作流以及當前倉庫中對應(yīng)的真實腳本# 1. 安裝依賴 npm install # 2. 打包 TypeScriptREADME 中的命令當前倉庫腳本名為 build npm run bundle # 對應(yīng)當前 package.json 中的 build: rolldown -c rolldown.config.mjs # 3. 檢查產(chǎn)物擴展目錄中會出現(xiàn) .tgz 文件對照當前 package.json 的scripts可確認模板命令與倉庫實際腳本的對應(yīng)關(guān)系{ build: rolldown -c rolldown.config.mjs, build:publish: rimraf *.tgz --glob || true yarn build npm pack cpx *.tgz ../../pre-install, test: vitest run }即build完成 rolldown 打包build:publish在清理舊產(chǎn)物后執(zhí)行build再用npm pack生成.tgz安裝包并復制到倉庫的pre-install目錄隨 Jan 應(yīng)用預裝test運行 vitest 測試。README 中提到的 “tgz 產(chǎn)物”即由npm pack產(chǎn)生。三、擴展元數(shù)據(jù)package.json 字段逐項解讀README 指出package.json定義了擴展的名稱、主入口、描述和版本等元數(shù)據(jù)fork 模板后必須更新其中的name與description。以當前模板文件為參照各關(guān)鍵字段含義如下字段當前值作用namejanhq/assistant-extension擴展包名是 Jan 識別擴展的唯一標識productNameJan Assistant展示在產(chǎn)品界面中的名稱version1.0.2擴展版本號maindist/index.js擴展主入口打包產(chǎn)物路徑nodedist/node/index.js節(jié)點側(cè)入口如存在獨立后端邏輯author/licenseJan servicejan.ai/AGPL-3.0作者與協(xié)議信息dependenciesjanhq/core唯一運行時依賴Jan 擴展核心包filesdist/*,package.json,README.md發(fā)布進.tgz包的文件白名單installConfig.hoistingLimitsworkspaces在 monorepo 中避免依賴被提升hoisting到工作區(qū)外這些字段并非擺設(shè)rolldown 構(gòu)建配置會直接讀取它們見下一節(jié)core 包的BaseExtension構(gòu)造參數(shù)name / productName / url / active / description / version見 extension.ts也與元數(shù)據(jù)一一對應(yīng)。四、構(gòu)建管線從 src/index.ts 到 dist/index.jsrolldown.config.mjs 完整展示了擴展的打包邏輯值得逐行理解import { defineConfig } from rolldown import pkgJson from ./package.json with { type: json } export default defineConfig([ { input: src/index.ts, output: { format: esm, file: dist/index.js, // 即 package.json 中的 main 字段 }, platform: browser, define: { NODE: JSON.stringify(${pkgJson.name}/${pkgJson.node}), VERSION: JSON.stringify(pkgJson.version), }, } ])要點入口是src/index.ts輸出為ESM 格式單文件dist/index.js正好落在package.json的main聲明位置platform: browser表明擴展代碼運行在瀏覽器/前端運行時環(huán)境中define在編譯期注入了兩個全局常量NODE與VERSION其值來自package.json的name/node/version字段。這與 src/types/global.d.ts 中的聲明相呼應(yīng)declare const NODE: string declare const VERSION: string也就是說擴展代碼在運行時可以直接讀取自身的包名與版本號無需額外配置。tsconfig.json 則規(guī)定了編譯口徑target: es2016、module: ES6、declaration: true聲明文件輸出到dist/types、sourceMap: true與 ESM 打包目標保持一致。五、擴展代碼骨架繼承 AssistantExtension 與生命周期模板 README 對擴展代碼有兩點核心提示大部分 Jan 擴展函數(shù)都是異步處理的擴展函數(shù)會返回Promiseany事件訂閱的典型寫法如下摘自 READMEimport { events, MessageEvent, MessageRequest } from janhq/core function onStart(): Promiseany { return events.on(MessageEvent.OnMessageSent, (data: MessageRequest) this.inference(data) ) }在 core 包中擴展體系以抽象類層次組織BaseExtension所有擴展的基類定義了name、url、active、description、version等屬性以及兩個必須實現(xiàn)的生命周期鉤子onLoad()/onUnload()還提供了registerModels、registerSettings等通用能力AssistantExtension助手類型擴展的抽象中間層聲明type()返回ExtensionTypeEnum.Assistant并要求實現(xiàn)三個抽象方法export abstract class AssistantExtension extends BaseExtension implements AssistantInterface { type(): ExtensionTypeEnum | undefined { return ExtensionTypeEnum.Assistant } abstract createAssistant(assistant: Assistant): Promisevoid abstract deleteAssistant(assistant: Assistant): Promisevoid abstract getAssistants(): PromiseAssistant[] }Assistant的數(shù)據(jù)形狀定義在 core/src/types/assistant/assistantEntity.ts包含avatar、id、object、created_at、name、description、model、instructions、tools、file_ids、metadata等字段并配有逐字段注釋是編寫助手相關(guān)擴展時最核心的類型契約。模板 README 指向的 Jan Extension Core 模塊文檔在本倉庫中即 core/README.md。六、默認助手實現(xiàn)解析onLoad、持久化與種子數(shù)據(jù)extensions/assistant-extension/src/index.ts 中的JanAssistantExtension是模板的參考實現(xiàn)onLoad()L17-L39展示了擴展加載時應(yīng)當完成的標準初始化序列async onLoad() { if (!(await fs.existsSync(file://assistants))) { await fs.mkdir(file://assistants) } // Run migrations if needed await this.runMigrations() const assistants await this.readAssistantsFromDisk() if (assistants.length 0) { const assistantWithParams { ...this.defaultAssistant, parameters: { temperature: 0.7, top_k: 20, top_p: 0.8, repeat_penalty: 1.12, }, } await this.createAssistant(assistantWithParams as Assistant) } }這里體現(xiàn)了 Jan 擴展編程模型的三個關(guān)鍵特征虛擬文件系統(tǒng)一切持久化都通過file://前綴路徑進行如file://assistants、file://assistants/id/assistant.json由janhq/core導出的fs模塊統(tǒng)一抽象屏蔽了不同平臺的真實磁盤差異。這是一個寫自定義擴展時必須記住的約定——不要直接使用 Node 的fs模塊。冪等初始化先確保目錄存在再執(zhí)行遷移最后僅在磁盤為空時寫入種子數(shù)據(jù)避免覆蓋用戶已自定義的助手對應(yīng)測試用例 “does not overwrite an existing persisted assistant on load”。種子參數(shù)默認助手Janid: jan、avatar: 、model: *表示適配所有已安裝模型附帶默認采樣參數(shù)temperature: 0.7 / top_k: 20 / top_p: 0.8 / repeat_penalty: 1.12其instructions是一段要求“按用戶語言回復、逐步推理、作為專業(yè)工具調(diào)用者分析信息缺口”的系統(tǒng)提示詞并帶有{{current_date}}日期占位符tools中默認掛了一個禁用狀態(tài)的retrieval工具附帶top_k: 2、chunk_size: 1024、chunk_overlap: 64的 RAG 檢索配置與檢索提示詞模板L333-L351。CRUD 方法本身也非常短小是“最小可運行擴展”的范例createAssistantL281-L292確保file://assistants/id/目錄存在后把助手序列化為縮進 JSON 寫入assistant.jsondeleteAssistantL294-L303存在即刪除assistant.json不存在則為空操作no-opgetAssistantsL275-L279優(yōu)先讀取磁盤數(shù)據(jù)磁盤為空時回退到內(nèi)置的defaultAssistant保證上層調(diào)用總能拿到至少一個可用助手。私有方法readAssistantsFromDisk還會跳過缺少assistant.json的目錄以及 JSON 解析失敗的損壞文件只記錄錯誤而不中斷整體加載。七、數(shù)據(jù)遷移機制版本化 .migration_version 與三級遷移JanAssistantExtension內(nèi)置了一套值得借鑒的輕量數(shù)據(jù)遷移方案L41-L95遷移版本記錄在file://assistants/.migration_version文件中當前版本常量CURRENT_MIGRATION_VERSION 3getCurrentMigrationVersion()讀取該文件文件缺失或內(nèi)容無法解析parseInt得到NaN時一律按版本 0處理從而保證遷移一定會補跑runMigrations()按currentVersion N的條件逐檔執(zhí)行遷移每完成一檔立即寫回版本號版本遷移內(nèi)容v1將舊版指令前綴You are a helpful AI assistant.改寫為You are Jan, a helpful AI assistant.并保留后續(xù)自定義內(nèi)容用startsWith 字符串截取實現(xiàn)v2將舊前綴助手整體改寫為新版默認指令含工具調(diào)用分析流程、{{current_date}}占位符并補齊默認采樣參數(shù)v3僅當助手指令與 v2 寫入的默認文本逐字完全一致時剝離身份前綴段落恢復為純默認指令用戶自定義提示詞不受影響遷移邏輯刻意保守每一檔都先做字符串精確匹配再改寫且失敗時只logger.error而不拋出確保單個助手損壞不會阻塞整個擴展啟動。這種“版本號文件 條件式補跑 精確匹配保護用戶數(shù)據(jù)”的模式可直接移植到任何需要持久化狀態(tài)演進的 Jan 擴展中。八、測試實踐用內(nèi)存文件系統(tǒng)驗證擴展邏輯模板自帶 src/index.test.ts展示了官方推薦的擴展測試方式用 vitest 對janhq/core的fs進行 mock以兩個內(nèi)存容器模擬虛擬文件系統(tǒng)——let files: Mapstring, string // 路徑 - 文件內(nèi)容 let dirs: Setstring // 已存在的目錄existsSync / mkdir / writeFileSync / readFileSync / rm / readdirSync全部落到Map/Set上L12-L45使得測試完全不依賴真實磁盤。測試覆蓋的斷言點恰好對應(yīng)第六、七節(jié)的所有行為getAssistants目錄不存在、目錄為空時均回退默認助手id: jan能并行讀取多個助手跳過無assistant.json的孤兒目錄與 JSON 損壞的條目createAssistant自動建目錄并寫入格式化 JSON斷言輸出含\n縮進目錄已存在時不再調(diào)用mkdirdeleteAssistant存在時刪除文件不存在時fs.rm根本不被調(diào)用onLoad自動創(chuàng)建file://assistants目錄、寫入遷移版本3、種子助手攜帶正確的默認參數(shù)、且不覆蓋已持久化的自定義助手遷移v1 精確替換前綴且保留尾部自定義文本You are a helpful AI assistant. Be concise.→You are Jan, a helpful AI assistant. Be concise.v2 寫入?yún)?shù)、v3 剝掉身份前綴已經(jīng)是版本 3 時不重復執(zhí)行遷移版本文件內(nèi)容為garbage時按 0 處理并補跑。運行方式即npm test對應(yīng)test: vitest run測試環(huán)境由 vitest.config.ts 與 src/test/setup.ts 配置。九、動手清單從模板到自定義擴展綜合 README 與源碼把模板改造為自己的擴展可以按以下清單執(zhí)行改名與元數(shù)據(jù)更新 package.json 的name、productName、description、author并提升version替換源碼src/是擴展的心臟README 明確允許整體替換。自定義擴展類應(yīng)繼承 core 中與你目標能力對應(yīng)的抽象基類如AssistantExtension實現(xiàn)其全部抽象方法并在onLoad()中完成初始化、onUnload()中做清理遵循異步約定所有擴展函數(shù)按異步風格編寫返回Promise需要響應(yīng)消息等應(yīng)用事件時使用janhq/core的events.on(...)訂閱持久化走 file:// 協(xié)議使用 core 導出的fs與joinPath管理數(shù)據(jù)目錄避免直接操作宿主磁盤構(gòu)建與驗證執(zhí)行npm install后運行build即 README 所述的打包步驟確認dist/index.js生成用npm pack或倉庫內(nèi)的build:publish生成.tgz產(chǎn)物回歸測試參照 src/index.test.ts 的內(nèi)存 fs mock 手法為你的存儲與遷移邏輯補測試再執(zhí)行npm test。以上流程均以當前倉庫的實際文件為準模板文檔見 extensions/assistant-extension/README.md構(gòu)建與類型配置見 rolldown.config.mjs、tsconfig.json擴展契約見 core/src/browser/extension.ts 與 core/src/browser/extensions/assistant.ts助手類型契約見 core/src/types/assistant/assistantEntity.ts。掌握這套“元數(shù)據(jù) 打包 生命周期 虛擬文件系統(tǒng)持久化 版本化遷移”的組合模式即可在 Jan 生態(tài)中開發(fā)并分發(fā)自己的功能擴展?！久赓M下載鏈接】janJan is an open source alternative to ChatGPT that runs 100% offline on your computer.項目地址: https://gitcode.com/GitHub_Trending/ja/jan創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考