English | 简体中文

交互式学习助理是一个运行在你自己电脑上的 AI 学习助手。它不是又一个聊天框：它会 制定学习计划、一项一项讲解、出选择题检验你是否真的理解、把你的疑问和笔记记下来，并把 这些整理成看得见的面板。所有数据都在你选择的文件夹里，不上传到任何第三方服务器——除了 你自己配置的大模型接口。

它自带一个「引导学习」助理和一套学习控件，装好、填一个模型 API Key 就能开始用。适合不 想折腾命令行的人：下载安装包 → 首次启动选一个放数据的文件夹 → 创建管理员 → 填 Key → 开始学习。

数据在你手里。 卸载应用不会删除你的数据——它在你首次启动时选择的那个文件夹里， 与程序本身分离。见 常见问题。

• 引导学习助理（内置） —— 一位懂得循序渐进的导师：先了解你想学什么，给出带多级编号 的学习计划，等你确认后逐项讲解；每讲完一个知识点出选择题检验，客观指出你的误区；学完 之后给出总结，列出需要加强的部分。详细设定见 内置助理。
• 计划 / 测验 / 脉络 / 笔记 / 图表 / 思考 / 参考资料 七个控件 —— 右侧面板上的学习工具：
  • 计划：一份可勾选进度的多级 TODO 列表，讲到哪里一目了然，可以跳到任意章节。
  • 测验：助手出题后，题卡可以直接作答，答完由助手判分解析；错过或跳过的题目可以补做。
  • 脉络：每一轮对话被自动归类到学习脉络里，可按主题回看。
  • 笔记：选中任意一段话写笔记，也可以给图表、表格、参考资料写；笔记带原文引用，点击 可以跳回原文位置。
  • 图表：助手画的结构图、流程图，以及它给出的表格，都在这里，点开即看。
  • 思考：一键让助手回顾整个过程，给出关于你学习状况的观察（难点、易混淆点、强项）。
  • 参考资料：本次对话用到的文件、网页，一目了然。
• 追问任意对象 —— 选中一段话，或点一下某个图表/表格/笔记/参考资料，就能针对它提问， 助手回答时会去读它当前的样子，而不是它被写下来时的样子。
• 助手（助理）可自定义 —— 人设提示词、可用工具、默认控件，都可以做成一个助理，供 自己反复使用，也可以公开给所有账号。对话开始时会复制一份，之后改助理不会影响已有对话。

答错会被客观指出；笔记可以点回原文。

图表与脉络面板自动汇集这个对话画过的和讨论过的。

• 资料库 —— 上传 PDF / Word / Excel / PPT / 纯文本等文件，或收藏网页，集中管理。
• @ 引用 —— 在输入框里打 @ 挑一份资料，它就成为这轮对话的上下文；也可以 @ 一个 工作区，让助手读取该工作区里的文件和对话。
• 文档解析 —— PDF 和 Office 文档本地提取文字，不需要联网；也可以配置云端解析服务 （MinerU、LlamaParse 等）来解析扫描件。
• 文件管理 —— 树状浏览工作区文件，支持新建、上传、重命名、移动（拖拽或对话框）、删除 （进回收站，字节保留）。
• 网页搜索与抓取 —— 内置 Bing / DuckDuckGo（免 Key），也支持 Tavily / SearXNG；助手 可以把确认有用的网页收藏成资料。
• 文件预览 —— 代码高亮、Markdown、Mermaid 图表、表格、图片、PDF 等直接在应用内查看。

上传的资料可以用 @ 引用，助手会读它。

• 多账号 —— 用户名 + 密码登录，每个账号有自己的工作区、对话、助理和上传文件，互相 不可见。三级权限：超级管理员 / 管理员 / 普通账号。
• 桌面控制面板 —— 图形界面启动、停止服务，选择数据目录，一键用手机打开（局域网扫码）。 支持 macOS（Apple 芯片 / Intel）、Windows、Linux。
• 用量统计 —— 每一次模型调用的 token 消耗都记账，可按天、按模型、按用途查看，控制成本。
• 中英双语 + 明暗主题。

到 Releases 下载对应你系统的 安装包：

安装包没有购买代码签名证书，所以系统会提示"来自身份不明的开发者"：

• macOS：在应用上点右键 → 打开 → 再点一次"打开"。只需一次。
• Windows：在 SmartScreen 提示里点 更多信息 → 仍要运行。

然后按下面的顺序走一遍：

1. 启动应用，控制面板出现。
2. 选择数据文件夹。面板会建议 ~/ilearnassist（你的主目录下），点一下就用它；也可以 自己挑一个位置。这里将存放你的数据库、工作区和上传的文件。选好后面板会记住它。
3. 创建超级管理员：填一个用户名和密码。这是这台机器上权限最高的账号，请记住它。 忘了可以用控制面板重置，见 常见问题。
4. 服务器会自动启动。点 打开应用，进入登录界面，用刚才的账号登录。
5. 填一个模型 API Key：点左侧菜单的 平台管理 → 模型服务，选一家你已经开通的服务商， 填入 API Key 并保存。填好之前，模型列表是空的——助手需要一个大模型才能工作。
6. 开始学习：回到首页，新建一个工作区，进去后新建对话，助理选 引导学习 · Guided Learning，然后告诉 它你想学什么。

从下载到能用的界面，只有这四步。

首次遇到防火墙询问时，请允许应用在本机（127.0.0.1）通信。默认不对外开放——只有你在控制 面板里主动打开"局域网共享"，手机才能访问。

需要 Node.js ≥ 20 和 pnpm ≥ 9。

git clone https://github.com/waychan23/ilearnassist.git
cd ilearnassist
pnpm install

# 配置：数据目录 + 模型 Key
cp .env.example .env
# 编辑 .env，至少填一个 DEEPSEEK_API_KEY（或其他服务商的 Key）

# 全新的数据目录里没有管理员，先创建一个
pnpm --filter @ilearnassist/server cli create-admin --username <你的用户名> --generate

pnpm dev

打开 http://localhost:5173 登录。后端监听 127.0.0.1:3720。

ILA_DATA_DIR 是必填的，.env.example 里已经设成 ./data（相对于项目根目录）。 代码里刻意没有默认值：那个目录决定你的数据在哪里、能不能在卸载后留下来。

首次启动时，下面的服务商会自动写入数据库，之后以 平台管理 → 模型服务 为准。国内和国际 的接口是分开的条目（两边的地址和 Key 都不通用），按你的网络情况选一个填 Key 即可。

只显示已经配置好的。 没填 Key 的服务商不会出现在对话的模型选择器里——与其给你一个 点了没反应的服务商，不如不给。任何 OpenAI 兼容的服务（Ollama、LM Studio、vLLM、自建网关…） 都可以在控制台里手动添加。

填了 Key，模型才会出现在选择器里。

「引导学习 · Guided Learning」是一个公开助理，所有账号都能在助理列表里看到并使用。它 同时启用了上面那七个控件，工作方式是：

1. 你提出一个学习主题（或它引导你明确一个）；
2. 它做网页搜索确认最新情况，然后给出学习计划：背景 → 一个整体实例（建立 Vision）→ 核心内容清单（一项一项讲，每轮通常只讲一项）；
3. 讲完一个知识点出一组选择题检验，等你作答后判分并客观解析——它不会自己把答案说出来；
4. 你答完，它问你是否继续；你说继续，它进入下一项；
5. 你可以随时打断追问、或按编号跳过某一项，它会回到主线；
6. 全部讲完做总结，包括内容清单和过程中发现的、需要加强的部分。

它的说话方式是深度、实战、最佳实践导向的，不是入门简介。

遇到专业术语，它会在第一次出现时用括号给出英文原文，避免中文翻译带来的歧义。

它属于创建它的那个管理员账号，但对所有账号可见可用。想按自己的方式教，在 助理 里 把它复制一份再改：改内置那条（只有管理员能改）会影响此后每一个新建的会话，而已经开始的 对话不受影响——对话在创建时就复制了一份助理设定，之后互不干扰。

学习计划会随讲解逐项长出来，讲完一项就用选择题检验。

我的数据在哪里？ 在你首次启动时选择的那个数据文件夹里（默认建议 ~/ilearnassist）。控制面板会显示这个 路径，并有一个按钮可以在文件管理器里打开它。里面包含：db/sqlite/ilearnassist.sqlite （数据库）、users/<用户名>/workspaces/（工作区与对话文件）、users/<用户名>/sources/ （上传的资料）。

怎么备份？ 复制上面那个文件夹就是完整备份。应用本身可以随时重装。

其中 <数据文件夹>/backups/ 是升级数据库前自动留下的快照（最近 5 份）。数据库结构变化时， 应用会在升级之前先复制一份，因为一次"成功但结果不对"的升级没有别的退路。

忘记密码了怎么办？ 用桌面控制面板的 重置管理员密码。它不需要服务在运行——忘了密码往往和别的问题一起 被发现，所以恢复手段不能依赖一个可能已经出问题的服务。从源码运行时，用 pnpm --filter @ilearnassist/server cli reset-admin --username <用户名> --password-stdin。 出于安全考虑，超级管理员自己的密码只能这样重置，不能在网页的控制台里改。

为什么模型列表是空的？ 没有填 API Key。到 平台管理 → 模型服务 配置一个，它会立刻出现在模型选择器里。

手机能一起用吗？ 可以。控制面板里有 局域网共享 开关，打开后会显示一个二维码，手机连同一个 Wi-Fi 扫码 即可。打开之前请想清楚：这会让你的工作区、对话和 API Key 配置对同一网络内的设备可见。 默认是关闭的。

卸载会删掉我的数据吗？ 不会。程序和数据在两个地方，卸载程序不动你的数据文件夹。想彻底清除，手动删除该文件夹。

怎么升级？ 数据库自动升级，不用你做任何事：新版本第一次启动时会自己完成，并且升级前会把数据库快照到 <数据文件夹>/backups/（上面那条）。面板会显示"数据库已从 vX 升级到 vY"，并给出快照路径。

应用本身需要你动手换一次：面板上会提示有新版本，点一下去下载新的安装包，覆盖安装即可—— 你的数据在数据文件夹里，覆盖安装不会碰它。这里没有做"一键自动更新"，因为 macOS 上的自动更新 要求应用有付费的代码签名，而这个项目没有购买证书（见上面的安装提示）。三个平台用同一套做法， 比一个只在两个平台能用的按钮更诚实。

支持哪些系统？ macOS（Apple 芯片与 Intel）、Windows、Linux 都有安装包。也可以直接从源码跑，任何能装 Node.js 20+ 的系统都行。

apps/server/      Fastify 后端 —— 路径、SQLite、Agent 循环、工具、路由
apps/web/         Vue 3 前端 —— Pinia store、对话界面、SSE 客户端
apps/desktop/     Electron 控制面板 —— 启动/停止服务，打包为桌面应用
packages/shared/  两端共用的类型（零依赖）
e2e/              Playwright 端到端测试
config/           config.yaml（可选的 config.local.yaml 覆盖）
docs/             架构与各子系统的详细文档

浏览器/服务端架构：后端是 Node/TypeScript（Fastify + SQLite + LangChain.js），前端是 Vue 3。桌面应用只是一个控制面板，它启动的是同一个后端，没有重新实现任何东西。

整套测试离线运行——不需要 API Key，也不访问网络。Agent 的部分跑在一个本地假的 OpenAI 兼容服务上，浏览器端到端测试会启动真实的服务器和一个一次性的数据库。

pnpm dev           # 同时跑后端 (:3720) 和前端 (:5173)
pnpm typecheck     # tsc + vue-tsc + e2e 规格
pnpm test          # 单元 + 集成测试
pnpm test:coverage # 同上，带覆盖率报告
pnpm test:e2e      # 浏览器端到端（需要先 pnpm exec playwright install chromium）
pnpm build         # 生产构建前端
pnpm desktop:dev   # 打包并启动桌面控制面板

提交前请确保 pnpm typecheck 和 pnpm test 都是干净的。新功能请带上测试； CLAUDE.md 记录了本仓库的约定，以及如何在不调用真实模型的前提下测试 Agent 行为。

本项目的全部第三方依赖及其许可证列在 CREDITS.md 中。感谢每一位维护者。

有一点值得单独说明：文件预览支持 CAD 格式的那几个包是 GPL-3.0，属于可选的对等依赖， 本项目刻意没有引入——这正是整个项目能够以 MIT 发布的原因。

MIT © ilearnassist contributors

• 迁移 —— 数据库结构的三种改法、不可变的迁移步骤，以及升级前的自动快照
• 架构 —— 系统总览、Agent 循环、沙箱、数据模型、SSE 协议
• 配置 —— config.yaml 完整参考、服务商与搜索配置
• 桌面应用 —— 控制面板、打包、签名与跨平台
• 控件系统 —— 右侧面板的控件契约、生命周期与新增步骤
• 提示词 —— 系统提示词目录与覆盖方式
• 用量统计 —— token 账本与统计页
• 会话写锁 —— 多客户端同时打开一个对话时的规则