LearnMargin

LearnMargin

Understand the content. Know how to learn.

把选定范围的课件、教材和笔记，变成带内容总览、详细讲解、例题与学习侧栏的 PDF。

LearnMargin 提供两个独立产品，共用按《学习之道》18 章整理的方法参考：

只有 AI 订阅、没有 API 的使用者，直接选择 Skill。Skill 不依赖安装软件或启动本地服务；软件也不要求用户先在 AI 客户端安装 Skill。两者可在同一仓库维护，但分别交付 learnmargin-skill.zip 与 Python 软件包。

软件包与独立 Skill 包可从 GitHub Releases 下载；版本变化见 更新记录。

直接使用 Skill

取得整个 skills/learnmargin/ 文件夹或 learnmargin-skill.zip，交给能够读取附件并生成文件的 AI 会话。支持技能目录的客户端也可按其规则安装该文件夹；不支持原生技能安装时，提供整个包并要求读取 SKILL.md 和相关参考文件即可。

例如：“按照 LearnMargin Skill，结合这份课本和 PPT，讲解 PPT 第 10～20 页，并参考课本相关内容。生成 A4 内侧栏 PDF，包含知识总览、详细讲解、少量学习提示、后置答案与休息安排。”

技能自带方法库，不要求再提供《学习之道》原书；用户仍需提供要学习的材料。PDF 使用当前 AI 环境已有的文件生成工具制作，可选脚本的依赖见技能使用说明。

软件使用流程

1. 导入一份或多份材料，查看解析结果。
2. 指定主材料的文件页码、幻灯片或章节范围，回查同文件其他位置的必要定义与前提，其余材料自动检索为参考；也可填写知识点，跨全部资料检索。页码模式可关闭主材料范围外回查。
3. 选择模型、输出语言和版式，填写必要的学习需求。输出默认简体中文，也可选择其他语言或自定义，不随材料语言自动切换。
4. 生成 PDF，预览、下载，或在网页阅读中查看原材料并返回原位置；导出 HTML 和 JSON 可继续编辑。

模型根据材料内容、知识依赖和讲解需要决定章节数量、顺序与边界，无需手动指定章数。讲义先给实质性的知识总览，再讲清概念、条件与推导。侧栏只保留有帮助的提示，需要作答的提示有后置参考答案与双向跳转。休息点按理解、例题和练习的预计负荷组合安排，短任务可跨章节合并，不按页数或每章一条的方式插入。用时估计及依据保存在生成数据中，实际休息以计时和疲劳为准。

同时提供课本和 PPT 时，讲义按知识点整合，注明每份资料怎么说、具体位置以及互补或差异。页码模式完整保留主材料的指定范围，其他文件仅补充相关内容；未找到相关内容会说明。PDF 保留关键解释，能独立阅读；网页的“查看原材料”打开对应页或章节，“返回讲义”回到原位置。

证明或例题依赖前文定义时，默认回查同一文件范围外的必要前提，以参考来源补入讲义，不增加无关学习主题。正文在使用前解释定义、符号角色和依赖的结论；缩写全称未知但定义已有依据时，照常讲清定义，不猜全称。审校发现关键前提仍无法核验时，指出具体缺口并停止生成，不把缺少依据的证明交付为完整讲解。

A4 标准版将正文和侧栏放在同一张 A4 内，适合打印与平板阅读；电脑宽版提供更多横向空间。两种版式都能在前端选择。

题目与答案双向定位到具体卡片。新导出的 PDF 使用 125% 跳转缩放，避免继承整页适应后只看出翻页；Web 会突出显示目标。独立 Skill 的附栏脚本可调整跳转缩放。

手写与扫描讲义：自动模式会对缺少可提取文字的图像页进行多模态转录；“手写讲义”模式会逐个图像单元识读文字与公式，即使页面带有印刷页脚。公式保留为 LaTeX，无法辨认处标记“待核对”。网页来源同时提供原图、识读文本和疑点；原文件不被覆盖。这个步骤需要模型支持图片，并会增加 API 调用。导出包保留 transcription.json，便于复核。真实笔迹小样本验证和开源 OCR 调研见识读说明。

本地启动

需要 Python 3.11+、Node.js 22+ 和 uv。以下命令适用于 PowerShell、Bash：

git clone https://github.com/Southwall-Tester/LearnMargin.git
cd LearnMargin
npm --prefix frontend ci
npm --prefix frontend run build
uv sync --frozen --extra dev
uv run playwright install chromium
uv run learnmargin --open

打开 **http://127.0.0.1:8765**。先点“体验内置示例”可检查 PDF 引擎；该示例是预先编写的内容，不调用模型。首次安装 Chromium 需要联网，PDF 渲染运行时不依赖 CDN。

Linux 还需中文字体和 Chromium 系统依赖：

sudo apt-get update
sudo apt-get install -y fonts-noto-cjk
uv run playwright install --with-deps chromium

Windows 也可以在完成安装后运行根目录的 Start-LearnMargin.cmd。

更新后先关闭旧服务，再重新启动；仅刷新页面不会更新后端。端口被占用时，启动器会提示处理旧服务，不打开旧页面。

模型与密钥

可从 DeepSeek、OpenAI 或兼容 API 预置开始，配置服务地址、模型名、密钥、视觉输入及 JSON 模式。

在模型设置中点击“测试连接”，可用少量固定文本检查当前地址、协议、模型和密钥是否能返回结果。仅在点击时发送一次请求，不发送学习材料、不保存密钥，也不自动重试；服务商可能按其 API 计费。测试文本通过不代表图片或整份讲义生成一定成功。

这表示协议兼容，不表示任意模型都支持图片或结构化输出。使用自定义模型时按其能力调整“视觉输入”和“JSON 模式”。不支持图片的模型无法处理纯扫描页。

“单次请求超时”默认 180 秒，可调至 600 秒；它限制每次模型请求（含服务重试和读取响应），不是整份讲义的总时长。“思考设置”按服务地址、协议和模型 ID 显示已确认的原生档位或开关，不统一映射等级，也不自动切换模型。未知服务或模型仅使用“不指定”；此时不发送思考参数，使用服务本身的默认行为（包括 DeepSeek，不再隐式关闭思考）。切换连接配置会清除旧档位并提示，旧偏好中的不兼容档位也会提示重选。支持范围、官方依据和扩展方式见 思考设置适配。降低强度可能减少等待，也可能影响复杂推理质量；连接测试只验证短文本请求，不证明长文生成速度。

扫描或手写材料每识读完一页就保存。保持已导入材料并重新生成时，会复用原图、文本、识读模式、服务地址、模型及思考设置均匹配的完整识读；调高超时不必重读已完成页。缓存不保存密钥，随对应导入材料删除。总览、检索主题和章节依据检查使用完整转录（含图表说明与疑点），避免再次集中发送全部扫描原图；各章讲解与审校仍附原图。未转录的图片仍发送，单个图像丰富章节仍可能耗时较长。

失败信息会保留具体阶段；逐页识读还记录文件、位置和耗时。重新生成会重新规划和生成章节，当前只复用逐页识读，不是完整任务的断点恢复。

浏览器输入的密钥只保留在当前页面和执行中的任务内，不写入浏览器存储、任务记录或导出文件。也可以复制 .env.example 为 .env，在本机填写；CLI 会加载它。LEARNMARGIN_API_KEY 只用于匹配 LEARNMARGIN_BASE_URL 的端点，DeepSeek 与 OpenAI 环境密钥也只用于各自配置的端点。

API 地址不能携带账号、查询参数或片段，请把密钥填在独立字段。远程服务使用 HTTPS；本机 HTTP 请求不会继承环境代理，HTTPS 仍支持已配置的代理。单次模型响应最多 8 MiB，请求总时限包含重试与读取响应；网关应遵循 Accept-Encoding: identity 返回未压缩 JSON。

材料先在本机解析；点击生成后，所选内容会发送到所配置的 API。知识点模式会分析全部勾选材料；页码模式会读取主材料指定范围，并分析其他勾选参考文件以检索相关内容。开启前提回查时，还会检索主材料范围外的内容，增加相应 API 请求。检索按完整单元分批进行，选出生成所需内容，并在导出包中保存检索位置与依据。修改配置和导入文件不会自动调用模型。

材料支持

PPTX 的复杂图表、公式、SmartArt，以及 DOCX 的浮动布局可能无法完整提取。对这些材料，可先导出 PDF 后导入。旧格式转换默认关闭，启用后也必须建立系统沙箱；失败时直接拒绝转换，没有普通进程回退。该开关不能通过上传请求打开。

Windows 需要 WSL 2。运行 learnmargin --setup-office（源码环境用 uv run learnmargin --setup-office）配置专用的 LearnMargin-Office 发行版，再在本机 .env 设置 LEARNMARGIN_ALLOW_LOCAL_OFFICE=1。配置命令下载并校验官方 Ubuntu Base，安装 LibreOffice、bubblewrap 和中文字体，不修改已有发行版；同名环境已存在时拒绝覆盖。Windows 本机无需安装 LibreOffice，材料和结果仅通过管道传递，转换器不能访问 Windows 盘、桌面或宿主网络。配置仅由这个显式命令执行，上传不会自动安装系统组件。

Linux 需要系统 LibreOffice、Python 3 和 bubblewrap 0.9 或更高版本，并设置同一本机启用开关。每次转换只读挂载输入和必需运行库，临时写入使用限额内存文件系统。macOS 暂无此转换沙箱，请先导出 PDF。平台条件及实际验证见安全说明。

上传前先限制实际请求体，压缩包按实际解压流校验大小与 CRC；XML 的 DTD/实体声明在编码识别后拒绝。文档解析在独立子进程内执行，限制为 150 秒和 2 GiB，超时或取消时终止该任务的进程树。资源限制不能替代对原生解析器的系统沙箱；完整边界与验证记录见安全说明。

单文件最多 50 MB、一次最多 8 份材料。每次导入最多 300 个内容单元；主材料与相关参考内容合计最多 60 个单元、10 万文本字符和 40 张图片。过大的范围会要求缩小，不静默截掉教材。知识点或参考资料检索最多分析 300 个单元、40 万文本字符。

分章后会检查各章是否拿到了必要依据，将后页或其他材料中的相关定义、完整结论分配给需要它的章节；各章尚未覆盖全部已选材料时，这会增加一次模型请求。检查记录保存在导出包的 section-source-review.json 中。

讲义应补足课件省略的必要解释，讲清概念、结论的含义、条件和推理，区分材料原文与助教补充。正文生成后会再次对照本节材料审校前提、来源转述、重复内容和侧栏答案。模型识读与审校仍可能出错，尤其是模糊手写、涂改和相似数学符号；这些步骤不能保证识读或教学内容一定正确。

Skill 内容与打包

技能的独立使用说明见 USAGE.md，智能体入口是 SKILL.md，参考资料入口是全书方法地图。

内置的是原创转述的方法摘要与应用设计，包含适用情境、学习动作和边界，不含完整电子书或用户教材。软件直接读取同一份方法库，先选相关章节再设计提示。修改通用学习规则时，同步更新 skill、应用生成规则与受影响的验证。

uv run python scripts/package_skill.py

独立技能包生成于 dist/learnmargin-skill.zip。

开发与检查

# 后端
uv run learnmargin
# 另一个终端启动前端；代理到8765
npm --prefix frontend run dev

uv run ruff check src tests scripts
uv run pytest
npm --prefix frontend test
npm --prefix frontend run build
uv run python scripts/check_skill.py
uv run --with pymupdf python -m pytest -q tests/test_skill_sidebars.py
uv run python -m build
uv run python scripts/package_skill.py
uv run python scripts/verify_package.py

真实浏览器端到端检查见 frontend/e2e/smoke.py，只用内置示例，不触发付费生成。需要显式验证真实 API 时：

uv run python scripts/smoke_api.py --live
uv run python scripts/smoke_api.py --live --mode pages

这会把项目自编示例发送到当前 API，可能产生费用；记录保存在被 Git 忽略的 artifacts/ 中。CI 不读取真实密钥或调用付费模型。

CI 会运行 Python 检查与测试、前端测试和构建、技能检查、软件与技能打包，并在仓库外的独立环境安装 wheel、启动服务和生成无 API 示例。打包检查记录保存在 artifacts/package-verification.json。设计和接口见 架构说明、接口契约，贡献流程见 CONTRIBUTING.md。

数据与部署

服务默认仅绑定 127.0.0.1，定位为单用户本机应用。材料、生成任务与产物存放在系统的 LearnMargin 用户数据目录，可用 LEARNMARGIN_DATA_DIR 指定其他位置。任务元数据会保存；进程重启后，未完成任务标记为中断，不假装自动恢复 API 请求。

暂不包含公网多用户认证、配额计费或云端隔离，不能把当前本地服务直接作为公共网站部署。

服务拒绝非本机连接及跨站 API 请求，限制上传和连接测试并发；新生成的讲义 HTML 只允许内置脚本，PDF 渲染启用 Chromium 系统沙箱，无法启用时直接报错。已有讲义不会被静默改写，重新生成或导出后才会带上新的 HTML 安全策略。

方法与接口来源

• 学习方法：Barbara Oakley《学习之道》，详见知识库来源与边界。
• API：DeepSeek 接入文档、视觉输入；OpenAI 结构化输出。
• 数学排版：KaTeX，资源及 MIT 许可证随项目保存；字体和其他依赖依其各自许可证使用。

项目代码采用 MIT License。