Electron+Vue3+AgentScope2：构建软考AI学习笔记桌面应用

备考软考的人大概都有过这样的经历手机里装了三四个 App一个记笔记一个刷题一个问 AI再加上浏览器里收藏的几十篇资料知识点散落在不同工具之间。真正坐下来复习的时候最耗时间的往往不是“学不会”而是“找不到自己之前学过什么”。笔记和题库分离、AI 回答和考点脱节这种碎片化才是备考效率最大的隐形杀手。这篇文章要做的是把这些零散环节收拢到一个桌面客户端里Electron 负责跨平台壳Vue3 TypeScript 负责界面与类型安全AgentScope2 负责 AI 侧的智能体编排。最终实现一个面向软考计算机技术与软件专业技术资格水平考试的学习笔记客户端不仅记录笔记还能基于笔记内容做 AI 答疑、知识点抽取、自动出题和复习计划生成。先给结论这个项目真正的技术难点不在 Vue3也不在 Electron而在“如何把 AI 能力嵌进一个本地优先的笔记工作流”。很多人以为接入 AI 就是调一个聊天接口但一旦进入备考场景就会发现你需要的是多个 AI 角色协作——一个负责答疑一个负责整理笔记一个负责出题。这正是 AgentScope2 这类多智能体框架发挥价值的地方。读完这篇文章你会得到一套可运行的工程骨架、关键代码、运行验证方法和排错清单。1. 为什么用 Electron Vue3 TypeScript 构建软考学习客户端1.1 软考备考的真实痛点软考分为初级、中级、高级三个级别常见科目包括软件设计师、数据库系统工程师、系统集成项目管理工程师、系统架构设计师、信息系统项目管理师等。考试形式一般是“综合知识客观题 案例分析主观题”高级科目还要写论文。这意味着备考过程不只是“看资料”还包括按科目和章节整理笔记、反复记忆概念、练习案例题、积累论文素材。如果用普通的在线笔记工具会遇到几个问题第一资料在云端地铁里没信号时想看笔记很麻烦第二笔记、题库、AI 问答互相隔离AI 不知道你记了什么答出来的内容经常和你的复习进度脱节第三学习数据没有统一结构到考前冲刺阶段想按知识点快速检索、生成错题本、做模拟题几乎都要靠手工整理。桌面客户端的价值就在这里本地优先、数据可控、可以跟 AI 能力深度耦合。1.2 技术选型判断选择 Electron Vue3 TypeScript主要基于三点判断。第一Electron 是目前把 Web 技术打包成桌面应用最成熟的方案生态完整electron-vite、electron-builder 等工具链已经非常顺手适合一个人快速做出跨平台产品。相比 TauriElectron 的 Node 运行时和原生模块生态更省心虽然包体积大但对学习工具类应用不是问题。第二Vue3 的组合式 API 非常适合这种“界面 状态 AI 异步请求”混合的交互场景。笔记列表、编辑器、AI 问答面板之间共享状态用ref、computed、watch组合起来比 Options API 清晰得多配合 TypeScript 的泛型推导数据流基本不会跑偏。第三TypeScript 的价值在这个项目里不是锦上添花而是刚需。笔记、标签、AI 响应、IPC 消息这些跨进程、跨模块的数据结构一旦没有类型约束接口一多就会失控。后面你会看到我们会把共享类型放在src/shared里让主进程、preload、渲染进程共用同一份定义。这里也提醒一句很多人习惯先在浏览器里打开 Vite 开发服务器调试 Vue3 界面结果发现窗口交互和按钮行为跟浏览器不一致比如窗口关闭、最小化按钮在某些情况下表现异常。这是因为浏览器环境根本没有 Electron 的窗口能力建议界面调试直接以 Electron 窗口为准浏览器只用来快速验证样式和布局。2. AgentScope2 在其中扮演什么角色2.1 从“AI 问答”到“多智能体协作”如果把 AI 能力做成一个简单的问答接口很快就发现不够用。比如用户问“什么是内聚和耦合”理想回答不仅要讲定义还要结合软考常考的选择题给出辨析。如果再进一步要求 AI “根据我最近一周的笔记生成 10 道章节自测题”这就不是单轮问答能解决的而是一个包含上下文检索、内容整理、题目生成、答案校验的流程。AgentScope2 是一个面向多智能体应用开发的开源框架核心价值在于把大模型调用封装成可编排的 Agent让多个 Agent 通过消息协作完成复杂任务。开发者不需要自己维护复杂的状态机和消息队列而是用框架提供的工作流能力把“答疑 Agent”“整理 Agent”“出题 Agent”串起来。从设计思路上看它解决的核心问题有两个一是降低多 Agent 应用的搭建成本二是让模型接入、消息传递、流程编排和运行观测统一起来。2.2 一个软考学习场景中的多智能体分工以我们正在构建的客户端为例AI 侧可以拆成四个角色。Agent 角色核心职责典型输入典型输出答疑 Agent结合笔记上下文回答知识点问题用户问题 相关笔记片段通俗讲解 考点提示整理 Agent从长文笔记中抽取术语、易混点原始笔记内容结构化知识点卡片出题 Agent按章节生成选择题与案例题章节笔记 考试大纲题目 答案 解析计划 Agent根据考试日期生成复习计划科目、章节进度、剩余天数分阶段复习计划这些 Agent 不是简单的前端传参调用而是存在依赖关系。比如出题之前整理 Agent 要先把笔记里的关键概念抽出来答疑的时候要先把相关笔记检索出来拼进上下文。这种编排逻辑如果写在 Vue3 组件里代码会非常臃肿而且很难调试。放到 AgentScope2 的服务端每个 Agent 独立定义、独立测试再用工作流串起来职责就清晰了。2.3 什么时候该用 AgentScope2如果你只是临时在笔记里做个“选中文字翻译”的小功能直接调大模型接口就够了没必要引入框架。但如果你要做的是一套有多个 AI 角色、有流程编排、后续还要扩展“自动生成思维导图”“论文素材库”等功能那 AgentScope2 这类框架就值得用。它让你把 AI 能力当成可组装的服务而不是写死在某个页面里的回调函数。需要注意的是AgentScope2 是 Python 生态的框架而 Electron 是 Node.js 环境。实际工程里不会把它们揉进同一个进程更合理的做法是Python 侧启动一个本地 AI 服务Electron 主进程通过 HTTP 或标准输入输出与它通信。后面第 8 章会给出具体实现。3. 系统整体架构与技术选型3.1 架构分层整个客户端从下往上分为四层。第一层是 Electron 主进程负责窗口管理、应用菜单、本地文件读写、IPC 消息处理和 AI 服务请求代理。第二层是 preload 脚本通过contextBridge把安全的 API 暴露给渲染进程渲染进程拿不到 Node 能力只能调用白名单方法。第三层是 Vue3 TypeScript 渲染进程负责笔记列表、编辑器、AI 问答面板等界面。第四层是独立的 Python AI 服务基于 AgentScope2 编排多智能体工作流监听本地端口。这种分层的关键好处是安全边界清晰渲染进程永远不接触 Node API模型密钥只存在于 Python 服务端环境变量中本地数据由主进程统一管理。即使渲染进程被注入恶意脚本攻击面也被限制在 preload 暴露的几个方法里。3.2 目录结构设计推荐使用 electron-vite 脚手架项目目录大致如下vue3-ts-ai-notes/ ├── src/ │ ├── main/ # Electron 主进程 │ │ ├── index.ts │ │ ├── store/noteStore.ts │ │ └── services/aiService.ts │ ├── preload/ # preload 脚本 │ │ └── index.ts │ ├── renderer/ # Vue3 渲染进程 │ │ ├── index.html │ │ └── src/ │ │ ├── main.ts │ │ ├── App.vue │ │ ├── views/ │ │ └── composables/ │ └── shared/ # 主进程与渲染进程共享类型 │ └── types/ ├── ai_service/ # AgentScope2 Python 服务 │ ├── main.py │ ├── agents/ │ └── requirements.txt ├── electron-builder.yml ├── package.json └── tsconfig.jsonsrc/shared是容易被忽略但非常关键的一层。Electron 主进程和渲染进程的 tsconfig 是两套配置共享类型如果放错位置编译时容易报“找不到模块”。把类型放在src/shared两个进程都通过路径别名引用能避免大量重复定义。4. 环境准备与项目初始化4.1 开发环境要求这个项目需要准备的基础环境如下版本号请以实际操作时为准本文重点演示通用思路Node.js 18 及以上建议使用 LTS 版本。包管理器使用 pnpm 或 npm本文以 pnpm 为例。Python 3.10 及以上用于运行 AgentScope2 AI 服务。一个可用的 OpenAI 兼容模型接口或者本地模型服务。Electron 依赖下载在某些网络环境下可能比较慢如果安装失败优先检查 Node 镜像配置和node_modules完整性不要直接跳过安装继续往下走。4.2 使用 electron-vite 初始化项目electron-vite 官方脚手架支持快速生成 Vue TypeScript 模板命令如下pnpm create quick-start/electron vue3-ts-ai-notes --template vue-ts cd vue3-ts-ai-notes pnpm install生成后先确认package.json中的脚本包含dev、build、build:win等命令。electron-vite 的好处是开发模式下主进程、preload、渲染进程三端都会热重载不需要手动同时启动 Vite 和 Electron。4.3 配置 TypeScript 与路径别名脚手架的tsconfig.json一般是分层的根目录负责整体引用tsconfig.node.json管主进程和 preloadtsconfig.web.json管渲染进程。一个基础配置示例如下{ compilerOptions: { target: ES2022, module: ESNext, moduleResolution: bundler, strict: true, jsx: preserve, resolveJsonModule: true, esModuleInterop: true, lib: [ES2022, DOM, DOM.Iterable], skipLibCheck: true, noEmit: true, paths: { renderer/*: [src/renderer/src/*], shared/*: [src/shared/*] } }, include: [src] }新版 TypeScript 对baseUrl的提示要留意option baseurl is deprecated and will stop functioning in typescript 7.0.。新项目里其实不需要写baseUrl直接配置paths就可以让别名生效。如果你看到这个废弃警告把它从tsconfig.json里删掉即可不要为了消除警告而忽略它背后的类型解析变化。5. 数据模型设计与 TypeScript 类型定义5.1 笔记与知识点的数据模型软考学习笔记和普通日记不同它需要有强烈的结构化倾向属于哪个科目、哪个章节、哪些标签、关联哪些真题。因此类型设计不能只写一个{ title, content }就完事。在src/shared/types/note.ts中定义笔记类型// src/shared/types/note.ts export interface Note { id: string title: string content: string category: string chapter: string tags: string[] createdAt: number updatedAt: number } export interface NoteQuery { keyword?: string category?: string chapter?: string tags?: string[] } export interface NoteSummary { id: string title: string category: string chapter: string updatedAt: number }category表示考试科目比如“软件设计师”“系统架构设计师”chapter表示教材章节比如“第二章 结构化开发方法”tags用于细粒度标记比如“内聚”“耦合”“数据流图”。这些字段后面会直接参与 AI 的上下文检索所以一开始就要设计好不要等界面写完了再补。5.2 AI 消息类型定义AI 相关的类型放在src/shared/types/ai.ts// src/shared/types/ai.ts import type { NoteSummary } from ./note export interface AIAskPayload { question: string noteIds?: string[] chapter?: string } export interface AIAnswer { answer: string relatedNotes?: NoteSummary[] createdAt: number } export interface QuizQuestion { id: string question: string options: string[] answer: number explanation: string }定义AIAskPayload时noteIds是可选的。这个字段的意义是让用户可以在“针对当前笔记提问”和“在整个知识库范围内提问”之间切换。AI 服务的责任是收到问题后先根据noteIds或chapter检索相关笔记再交给答疑 Agent 生成回答。6. Electron 主进程与 IPC 通信实现6.1 创建主窗口src/main/index.ts负责创建窗口和注册 IPC 处理器。安全的 Electron 窗口配置必须开启contextIsolation、关闭nodeIntegrationpreload 路径要精确指向编译产物。// src/main/index.ts import { app, shell, BrowserWindow, ipcMain, Menu } from electron import { join } from path import { electronApp, optimizer, is } from electron-toolkit/utils import { NoteStore } from ./store/noteStore import { AIService } from ./services/aiService let mainWindow: BrowserWindow | null null const noteStore new NoteStore() const aiService new AIService() function createWindow(): void { mainWindow new BrowserWindow({ width: 1280, height: 820, minWidth: 960, minHeight: 640, show: false, title: 软考学习 AI 笔记, webPreferences: { preload: join(__dirname, ../preload/index.js), contextIsolation: true, nodeIntegration: false, sandbox: false } }) mainWindow.on(ready-to-show, () { mainWindow?.show() }) // 外部链接一律交给系统浏览器打开避免新窗口抢占应用窗口 mainWindow.webContents.setWindowOpenHandler((details) { shell.openExternal(details.url) return { action: deny } }) if (is.dev process.env[ELECTRON_RENDERER_URL]) { mainWindow.loadURL(process.env[ELECTRON_RENDERER_URL]) } else { mainWindow.loadFile(join(__dirname, ../renderer/index.html)) } } app.whenReady().then(() { electronApp.setAppUserModelId(com.example.ruankao-notes) app.on(browser-window-created, (_, window) { optimizer.watchWindowShortcuts(window) }) // 注册 IPC 处理器 ipcMain.handle(notes:list, () noteStore.list()) ipcMain.handle(notes:save, (_event, note) noteStore.save(note)) ipcMain.handle(notes:delete, (_event, id: string) noteStore.delete(id)) ipcMain.handle(ai:ask, async (_event, payload) aiService.ask(payload)) createWindow() app.on(activate, () { if (BrowserWindow.getAllWindows().length 0) createWindow() }) }) app.on(window-all-closed, () { if (process.platform ! darwin) { app.quit() } })这段代码里值得注意的两点一是所有 IPC 处理器都写在app.whenReady()之后避免窗口创建后处理器还没注册二是noteStore和aiService是主进程单例它们的生命周期和主进程一致不会因为窗口刷新而丢失。6.2 通过 preload 暴露安全 APIpreload 脚本是渲染进程与主进程之间的唯一桥梁。不要直接暴露ipcRenderer而是把具体方法封装成业务语义明确的 API。// src/preload/index.ts import { contextBridge, ipcRenderer } from electron import type { Note } from ../shared/types/note import type { AIAskPayload, AIAnswer } from ../shared/types/ai const api { getNotes: (): PromiseNote[] ipcRenderer.invoke(notes:list), saveNote: (note: Note): PromiseNote ipcRenderer.invoke(notes:save, note), deleteNote: (id: string): Promiseboolean ipcRenderer.invoke(notes:delete, id), askAI: (payload: AIAskPayload): PromiseAIAnswer ipcRenderer.invoke(ai:ask, payload) } contextBridge.exposeInMainWorld(api, api)对应地在渲染进程需要声明window.api的类型否则 TypeScript 会报Property api does not exist on type Window。// src/renderer/src/env.d.ts import type { Note } from shared/types/note import type { AIAskPayload, AIAnswer } from shared/types/ai declare global { interface Window { api: { getNotes(): PromiseNote[] saveNote(note: Note): PromiseNote deleteNote(id: string): Promiseboolean askAI(payload: AIAskPayload): PromiseAIAnswer } } } export {}6.3 主进程处理本地存储学习数据量不大时用electron-store把数据持久化到用户数据目录下的 JSON 文件就够了。它的读写是同步的接口简单适合单机单人使用。// src/main/store/noteStore.ts import Store from electron-store interface NoteRecord { notes: Note[] } export class NoteStore { private store new StoreNoteRecord({ name: study-data, defaults: { notes: [] }