企业官网建设流程全解析

软考备考这件事，很多人卡在同一个地方：资料越攒越多，笔记越来越乱，错题解析看不进去，知识体系始终形不成闭环。这次我们直接用 Vue3 + TypeScript + Electron + AgentScope2 这套组合，做一个本地优先的“软考学习 AI 笔记客户端”，把笔记整理、AI 问答、错题解析、批量整理几件事全部串起来。

先说结论。这是一个桌面应用，界面层用 Vue3 + TypeScript，桌面容器用 Electron，AI 能力由 AgentScope2 智能体服务承担。因为 AgentScope2 属于 Python 生态，工程上会把 AI 服务拆成一个本地 Python 进程，Electron 通过 HTTP 调用它。这样做的收益很明显：前端保持干净的 TypeScript 类型安全，Agent 侧的模型切换、多智能体编排、批量任务都在 Python 里完成，后续想换模型或加 Agent，都不用动界面代码。

如果你正在学 Vue3、TypeScript、Electron，或者想把 AgentScope2 落地到一个真实产品里，这篇文章可以直接收藏。下面按真实开发顺序展开：技术选型、环境准备、项目初始化、主进程与渲染进程通信、AgentScope2 服务接入、核心功能实现、批量任务、性能观察和问题排查。

1. 核心能力速览

这一套组合的关键点不是“某个框架多强”，而是把前端、桌面壳、智能体三块各自的优势拉满。Electron 负责稳定的桌面体验，Vue3 + TS 负责界面和状态管理，AgentScope2 负责让多个 AI 角色协同工作。软考学习场景天然适合这种结构：笔记是本地资产，AI 是增强手段，两者不冲突。

2. 适用场景与使用边界

2.1 适合谁

这个客户端适合三类人。第一类是软考备考者，需要把分散的考点、错题、教材笔记统一管理，并用 AI 辅助讲解和总结。第二类是前端工程师，想用 Vue3 + TypeScript 开发一个完整的 Electron 桌面应用，学习主进程、preload、IPC 的标准写法。第三类是对 AgentScope2 感兴趣的同学，想看看多智能体框架怎么接入真实业务，而不是只跑一个 demo。

2.2 能解决什么问题

它能解决三个具体问题。一是笔记整理成本高，零散内容交给 AI 变成结构化考点；二是错题复盘效率低，AI 可以按“知识点 + 错误原因 + 相似题”的路径帮你拆解；三是知识体系不完整，多个 Agent 分别负责笔记、问答、出题，形成一条完整学习链路。

2.3 使用边界与合规提醒

先强调几点边界。软考题目和教材内容有版权，笔记和题库素材只应用于个人学习，不要批量搬运或再分发。涉及他人肖像、声音、敏感个人信息的内容不要存入知识库。如果考试组织方明确禁止使用 AI 辅助答题，请遵守考试规则。AI 生成的知识点总结、题目解析存在幻觉风险，重要内容一定要回到官方教材核对。生产环境使用时要确认模型服务所在网络的合规性，不要把云 API Key 写死在 Electron 渲染进程里。

3. 技术架构与环境准备

3.1 整体架构

整个系统分四层：

这个结构里，Electron 和 Python 服务是“双进程”关系。Electron 启动时拉起 Python 服务，退出时关闭，中间通过http://127.0.0.1:端口通信。好处是 AgentScope2 的热更新、模型配置、依赖管理都不影响前端，前端也不需要了解 Python 细节。

3.2 环境准备清单

建议按下面的清单准备环境，版本以当前稳定版为准：

Node.js 18 或更高版本 pnpm / npm 任意一种包管理器 Python 3.10 或更高版本 Git electron-builder（用于打包时安装）

如果 AI 服务走云端 API，需要准备对应的 API Key。如果走本地模型，需要评估显卡显存、模型文件大小和磁盘空间，这一步没有统一数值，必须按实际选择的模型版本测试。

3.3 项目目录规划

soft-exam-ai-notes/ ├── electron.vite.config.ts ├── package.json ├── src/ │ ├── main/ # Electron 主进程 │ │ └── index.ts │ ├── preload/ # preload 脚本 │ │ └── index.ts │ └── renderer/ # Vue3 渲染进程 │ ├── index.html │ └── src/ │ ├── App.vue │ ├── main.ts │ ├── stores/ │ ├── views/ │ └── components/ ├── ai_service/ # AgentScope2 本地服务 │ ├── requirements.txt │ ├── app.py │ └── agents/ └── resources/

把前端和 AI 服务分目录管理，后续打包时各自处理依赖，互不干扰。

4. 项目初始化与 Electron 主进程开发

4.1 初始化项目

推荐直接用 electron-vite 的脚手架，它把主进程、preload、渲染进程三部分整合得很好：

npm create @quick-start/electron@latest soft-exam-ai-notes cd soft-exam-ai-notes npm install npm run dev

项目生成后，electron.vite.config.ts默认把src/main、src/preload、src/renderer三个入口分开构建。可以做一点调整，例如配置路径别名：

// electron.vite.config.ts import { defineConfig } from 'electron-vite' import vue from '@vitejs/plugin-vue' import { resolve } from 'node:path' export default defineConfig({ main: {}, preload: {}, renderer: { resolve: { alias: { '@': resolve(__dirname, 'src/renderer/src') } }, plugins: [vue()] } })

4.2 主进程基础代码

主进程要完成三件事：创建窗口、启动 Python AI 服务、注册 IPC 通道。安全配置上，必须开启contextIsolation，关闭nodeIntegration，所有能力通过 preload 暴露：

// src/main/index.ts import { app, BrowserWindow, ipcMain, dialog } from 'electron' import { spawn, ChildProcess } from 'node:child_process' import path from 'node:path' const AI_SERVICE_URL = 'http://127.0.0.1:8730' let aiProcess: ChildProcess | null = null let mainWindow: BrowserWindow | null = null function startAiService() { const scriptPath = path.join(app.getAppPath(), 'ai_service', 'app.py') aiProcess = spawn('python', [scriptPath], { cwd: path.dirname(scriptPath), stdio: ['ignore', 'pipe', 'pipe'] }) aiProcess.stdout?.on('data', (chunk) => { console.log('[ai_service]', chunk.toString()) }) aiProcess.stderr?.on('data', (chunk) => { console.error('[ai_service:error]', chunk.toString()) }) } function createWindow() { mainWindow = new BrowserWindow({ width: 1280, height: 800, webPreferences: { preload: path.join(__dirname, '../preload/index.js'), contextIsolation: true, nodeIntegration: false } }) if (process.env.ELECTRON_RENDERER_URL) { mainWindow.loadURL(process.env.ELECTRON_RENDERER_URL) } else { mainWindow.loadFile(path.join(__dirname, '../renderer/index.html')) } } app.whenReady().then(() => { startAiService() createWindow() }) app.on('window-all-closed', () => { if (process.platform !== 'darwin') { app.quit() } }) app.on('quit', () => { aiProcess?.kill() })

Python 服务是在应用启动时由主进程拉起的，所以开发时先确认本机python命令可用。如果用户机器上同时装了多个 Python 版本，建议在配置项里把解释器路径做成可选的。

4.3 进程生命周期管理

这里有一个容易踩的坑：app.getAppPath()在开发环境和打包环境指向的目录不同。开发时它是项目根目录，打包后是 asar 内路径，Python 脚本如果在 asar 里会无法直接替换依赖。稳妥做法是打包时把ai_service目录通过 extraResources 放到资源目录，主进程用process.resourcesPath取真实路径。

const resourceRoot = app.isPackaged ? process.resourcesPath : app.getAppPath() const scriptPath = path.join(resourceRoot, 'ai_service', 'app.py')

这样开发和生产路径都能正确处理。

5. Vue3 + TypeScript 渲染层与 IPC 通信

5.1 preload 暴露安全接口

渲染进程不能直接拿到 Node 能力，所有桌面功能和 AI 请求都通过contextBridge暴露：

// src/preload/index.ts import { contextBridge, ipcRenderer } from 'electron' const api = { askAI: (question: string, context: string) => ipcRenderer.invoke('ai:ask', { question, context }), organizeNote: (title: string, content: string, topic: string) => ipcRenderer.invoke('ai:organize-note', { title, content, topic }), selectMarkdownFile: () => ipcRenderer.invoke('dialog:select-file') } contextBridge.exposeInMainWorld('api', api)

5.2 渲染进程类型声明

前端要用 TypeScript 完整覆盖这个对象，在src/renderer/src/env.d.ts里补充全局类型：

// src/renderer/src/env.d.ts export {} declare global { interface Window { api: { askAI(question: string, context: string): Promise<{ answer: string }> organizeNote( title: string, content: string, topic: string ): Promise<{ note: string }> selectMarkdownFile(): Promise<string[]> } } }

主进程侧注册对应的ipcMain.handle：

// src/main/index.ts import { ipcMain, dialog } from 'electron' import { askAgentService, organizeNoteRequest } from '../common/ai-client' ipcMain.handle('ai:ask', async (_event, payload) => { return askAgentService('/api/chat', payload) }) ipcMain.handle('ai:organize-note', async (_event, payload) => { return organizeNoteRequest(payload) }) ipcMain.handle('dialog:select-file', async () => { const result = await dialog.showOpenDialog({ filters: [{ name: 'Markdown', extensions: ['md', 'txt'] }] }) return result.filePaths })

这里的askAgentService是在主进程里请求 Python 服务的 HTTP 客户端函数，使用 Node 的fetch或axios。注意不要在 preload 里直接请求 Python 服务，统一走主进程，以后加鉴权、加日志、加超时重试都方便。

5.3 笔记列表页示例

渲染层用 Pinia 管理笔记状态，一个简化版笔记 store：

// src/renderer/src/stores/note.ts import { defineStore } from 'pinia' import { ref } from 'vue' export interface NoteItem { id: string title: string topic: string content: string updatedAt: number } export const useNoteStore = defineStore('note', () => { const notes = ref<NoteItem[]>([]) async function loadNotes() { // 从本地文件或 SQLite 读取 } async function saveNote(note: NoteItem) { // 写入本地 } return { notes, loadNotes, saveNote } })

聊天面板组件通过window.api.askAI调用 AI 服务，代码里不需要感知 Python 进程的存在：

<script setup lang="ts"> import { ref } from 'vue' const question = ref('') const answer = ref('') const loading = ref(false) async function handleAsk() { if (!question.value.trim()) return loading.value = true try { const result = await window.api.askAI(question.value, '') answer.value = result.answer } finally { loading.value = false } } </script>

注意 AI 服务返回的是 Markdown 内容，渲染时用 markdown-it 或 md-editor-v3 做富文本展示，代码块和高亮都能保留。

6. AgentScope2 智能体服务接入

6.1 为什么单独做 Python 服务

AgentScope2 是面向多智能体场景的 Python 开发框架，负责模型统一配置、Agent 生命周期、消息流转和工具调用。让 Electron 直接内嵌 Python 不现实，独立本地服务是最干净的集成方式。前端只关心 HTTP 接口，AgentScope2 内部细节全部收敛在ai_service目录里。

6.2 安装依赖

cd ai_service pip install fastapi uvicorn pydantic # 按官方文档安装 agentscope2 pip install agentscope2

具体包名和依赖版本以 AgentScope2 官方文档为准，不同版本初始化方式可能有差异。

6.3 模型与 Agent 初始化

下面是一个基于 AgentScope 常见写法的示例，AgentScope2 的 API 名称或参数如果调整，以官方文档为准：

# ai_service/app.py import agentscope from fastapi import FastAPI from pydantic import BaseModel agentscope.init( model_configs=[ { "config_name": "exam-bot", "model_type": "openai", "model_name": "gpt-4o-mini", "api_key": "替换为你的API Key", } ] ) app = FastAPI(title="软考AI笔记服务") class ChatRequest(BaseModel): question: str context: str = "" class NoteRequest(BaseModel): title: str content: str topic: str = "" @app.get("/health") async def health(): return {"status": "ok"}

如果使用本地模型，model_configs里要换成本地推理服务地址，例如兼容 OpenAI 协议的http://127.0.0.1:8000/v1，模型名称填本地部署的模型名。选本地模型还是云 API，先看自己的显存和预算，没有统一结论。

6.4 定义多个学习 Agent

Agent 是这套系统的核心。按软考学习场景拆四个角色：

自定义 Agent 的常见写法：

# ai_service/agents/note_agent.py from agentscope.agent import AgentBase from agentscope.message import Msg class NoteAgent(AgentBase): """把零散笔记整理成结构化学习内容""" def __init__(self, name: str = "note_agent", **kwargs): super().__init__(name=name, **kwargs) def reply(self, msg: Msg) -> Msg: system_prompt = ( "你是软考备考笔记整理助手。请把用户提供的内容整理成四部分：\n" "1. 核心考点\n" "2. 知识点大纲\n" "3. 容易混淆的概念\n" "4. 3 个自测问题\n" "输出使用 Markdown 格式。" ) response = self.model( [ {"role": "system", "content": system_prompt}, {"role": "user", "content": msg.content}, ] ) return Msg(name=self.name, content=response.text)

QuestionAgent 的提示词可以强制它先定位考点再展开分析，避免直接罗列答案：

# ai_service/agents/question_agent.py from agentscope.agent import AgentBase from agentscope.message import Msg class QuestionAgent(AgentBase): def reply(self, msg: Msg) -> Msg: system_prompt = ( "你是软考真题解析助手。用户会给你一道题，请按这个顺序回答：\n" "1. 先判断这道题属于哪个科目和章节；\n" "2. 列出考察的知识点；\n" "3. 指出常见错误选项的错误原因；\n" "4. 给出正确解题过程；\n" "5. 生成 1 道同考点相似题。" ) response = self.model( [ {"role": "system", "content": system_prompt}, {"role": "user", "content": msg.content}, ] ) return Msg(name=self.name, content=response.text)

6.5 本地知识库检索

要让 AI 回答得更贴近考试范围，可以把笔记和教材摘录做成一个小型知识库。实现不复杂：启动时把笔记拆成片段建索引，收到问题时先检索最相关的片段拼进上下文，再交给 Agent 回答。

def build_context(question: str, note_index: list[dict], top_k: int = 3) -> str: # 简化检索：按关键词和分数字段排序 scored = [] for item in note_index: score = keyword_score(question, item["text"]) scored.append((score, item)) scored.sort(key=lambda x: x[0], reverse=True) return "\n".join(item["text"] for _, item in scored[:top_k])

正式项目可以换成向量检索，但首次做 MVP 用关键词检索也够用，重点是先把链路跑通。

7. 核心学习功能与效果验证

7.1 笔记整理功能

功能说明：用户在编辑器里粘贴零散笔记，一键调用 NoteAgent，输出结构化学习笔记，并保存到本地。

操作步骤：

1. 新建一篇笔记，输入标题和正文。
2. 点击“AI 整理”。
3. 渲染进程调用window.api.organizeNote。
4. 主进程转发到 Python 服务的/api/organize-note。
5. 前端展示整理结果，用户确认后覆盖或另存。

判断标准：返回结果包含“核心考点 / 知识点大纲 / 易混点 / 自测问题”四个部分，且 Markdown 渲染正常。如果结果只有一段平铺文字，优先检查 Agent 的 system prompt 是否生效。

7.2 AI 问答功能

功能说明：针对当前笔记或某个考点提问，ChatAgent 用分步骤方式讲解。

输入示例：

关系数据库中的候选键和主键有什么区别？帮我用通俗例子说明。

预期结果：回答分三步，先给定义，再给例子，最后给一个易错点。验证时重点看回答是否引用了当前笔记的上下文。如果回答明显偏离知识库，检查build_context返回的内容是否为空。

7.3 错题解析与相似题生成

功能说明：把错题粘贴到界面，QuestionAgent 输出考点、错误原因、解题过程、相似题。

验证流程：

1. 准备一道真题或模拟题。
2. 调用 QuestionAgent。
3. 检查输出是否包含“章节判断、知识点、错误选项分析、相似题”。
4. 如果相似题质量差，可在提示词中加入“难度与真题一致，考察同一考点”的要求。

7.4 学习计划生成

功能说明：用户输入考试日期、当前复习状态、每天可用时间，PlanAgent 输出周计划。

# ai_service/agents/plan_agent.py class PlanAgent(AgentBase): def reply(self, msg: Msg) -> Msg: system_prompt = ( "你是软考备考规划助手。输入会包含考试日期、每日可用时间和薄弱科目。" "请输出：周计划表、每日任务、阶段里程碑。" "时间安排要具体到小时，不要给出空泛建议。" ) response = self.model( [ {"role": "system", "content": system_prompt}, {"role": "user", "content": msg.content}, ] ) return Msg(name=self.name, content=response.text)

验证时要把日历场景写到 prompt 里，否则模型容易生成“第一周复习，第二周刷题”这类没有约束力的计划。

8. 接口 API 与批量任务

8.1 接口服务启动方式

开发时手动启动 Python 服务：

cd ai_service uvicorn app:app --host 127.0.0.1 --port 8730

生产环境由 Electron 主进程在app.whenReady里自动拉起，前端无需感知。

8.2 API 调用示例

以下是一个调用/api/chat的 Python 脚本示例：

import requests url = "http://127.0.0.1:8730/api/chat" payload = { "question": "什么是死锁？产生死锁的四个必要条件是什么？", "context": "当前笔记：操作系统 进程管理" } response = requests.post(url, json=payload, timeout=120) print(response.json())

前端统一走 IPC，不直接跨域请求 Python 服务。这样以后加本地端口校验、请求加密、重试机制都只需要该主进程一处。

8.3 批量任务设计

批量整理笔记是高频需求。设计上不要同步处理大量请求，用一个简单的任务队列：

# ai_service/tasks.py import asyncio from uuid import uuid4 task_store = {} async def run_batch_organize(items: list[dict]) -> str: task_id = str(uuid4()) task_store[task_id] = {"status": "running", "progress": 0, "results": []} async def worker(): for index, item in enumerate(items): result = await organize_one(item) task_store[task_id]["results"].append(result) task_store[task_id]["progress"] = int((index + 1) / len(items) * 100) task_store[task_id]["status"] = "done" asyncio.create_task(worker()) return task_id

前端轮询任务进度：

const taskId = await window.api.startBatchOrganize(selectedNotes) const timer = setInterval(async () => { const progress = await window.api.getBatchProgress(taskId) if (progress.status === 'done') { clearInterval(timer) } }, 2000)

批量任务必须考虑失败重试和断点继续。一个简单策略是：每个条目独立记录状态，失败的条目单独重试 2 次，仍然失败的在结果里标记failed，并把原始输入保留下来，方便用户手动处理。

9. 资源占用、性能观察与常见问题排查

9.1 资源占用观察方法

Electron 应用本身的内存占用取决于页面复杂度，Vue3 应用配合局部刷新和虚拟列表可以控制得比较好。真正的资源大头是 AI 服务：如果用云 API，本机只承担网络请求，资源占用很低；如果用本地模型，显存和内存会成为关键瓶颈。

常用观察命令：

# 查看显存 nvidia-smi # 查看 Python 服务进程占用 ps aux | grep app.py

本地模型场景下，显存占用由模型参数量、量化精度和输入长度共同决定。8B 级别的量化模型和 70B 级别的全精度模型占用完全不同，不能用一个固定数字覆盖所有情况。实际部署时以本机测试为准，先跑一次最小输入，观察显存曲线，再逐步加长输入。

9.2 降低资源占用的方法

• 批量任务加并发限制，一次只处理 1 到 2 个请求。
• 本地模型优先选择量化版本。
• 长文本先截断或做摘要，再交给 Agent。
• 避免在渲染进程里保存大量 Markdown 字符串，渲染销毁时释放组件。
• 知识库索引启动时加载一次，不要每次请求都重建。

9.3 常见问题排查清单

9.4 开发环境与生产环境差异

开发时主进程和渲染进程都是热更新，Python 服务需要手动管理。生产打包时要注意：ai_service的依赖要打包进 extraResources，并且 Python 解释器要随应用分发，比较麻烦。如果只是自用，可以保留“本机已安装 Python”的假设；如果要分发给非技术用户，需要把 Python 内置依赖一并处理，或者考虑用 PyInstaller 把服务打包成独立可执行文件。

10. 最佳实践与后续扩展

10.1 工程化建议

第一次做这类应用，先跑通最小闭环：笔记列表读写、一个 Agent 问答、一个批量任务。不要一开始就堆八个 Agent。

模型配置文件统一放在ai_service/config目录，不要散落在各 Agent 代码里。API Key 用环境变量注入，开发环境用.env文件，生产环境走系统配置或主进程配置，禁止写进 Vue 组件。

批量任务要加任务日志，每个条目的输入、输出、耗时、失败原因都记录。这样出问题时不用猜。

IPC 接口尽量收敛成少量语义化方法，而不是每个功能一个。ai:ask、ai:organize-note、batch:start、batch:progress四个接口就能覆盖大部分场景。

10.2 数据与隐私

笔记默认存本地，AI 请求要明确告诉用户哪些内容会发送到模型服务。使用云 API 时，不要在提问里粘贴账号密码、身份证号等敏感信息。使用本地模型时，知识库文件和模型文件要放在用户数据目录下，不要和程序代码混在一起。

10.3 内容合规

题库、教材、官方真题的版权边界要清楚。个人学习场景可以整理摘录，但做公开发布或商业产品时必须获得授权。AI 生成的知识总结和题目解析，发布前要做人工复核，避免把模型幻觉内容当作考试事实。

10.4 后续可以扩展的方向

这个骨架跑通后，可以继续加三类能力。一是间隔重复复习，把“自测题”和“错题”数据做成艾宾浩斯复习队列。二是知识图谱，从笔记中抽取概念和关系，生成考点关联图。三是把 AgentScope2 的更多能力接进来，例如让多 Agent 协同完成“章节复盘 + 出题 + 批改 + 讲解”的完整流程。

建议先把最基础的笔记整理和 AI 问答跑通，再逐步加批量任务和本地知识库。这个项目最值得试的点是“AI 服务与桌面端分离”的架构，它可以让你在完全不改前端的情况下，切换不同模型和不同 Agent 策略，对软考学习和 Agent 开发实践都有直接帮助。