{"id":"584d1eb5-a9d9-464a-9fa3-c3418efc8f6d","slug":"learnmargin","kind":"skill","name":"LearnMargin","summary":"将课件、教材与笔记整合为带总览、学习侧栏和参考答案的 PDF；提供无需 API 的独立 AI Skill 与本地 Web 应用。","owner":"Southwall-Tester","repoUrl":"https://github.com/Southwall-Tester/LearnMargin","license":"MIT","licenseTier":"permissive","trust":"community","stars":5,"match":null,"fewStars":false,"format":"skill","createdAt":"2026-10-04T07:15:08.000Z","addedAt":"2026-10-14T06:32:10.558Z","logoUrl":"https://avatars.githubusercontent.com/u/254047579?u=57d5c7e4bda3973d3d57f79989be15f042b94374&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents"],"tags":["ai","deepseek","education","fastapi","learning-to-learn","pdf-generation","react"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-17T08:20:40.333Z","sample":false,"url":"https://conduits.dev/tools/learnmargin","language":"Python","transports":["stdio"],"install":{"pypi":"learnmargin"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# LearnMargin\n\n**Understand the content. Know how to learn.**\n\n[![CI](https://github.com/Southwall-Tester/LearnMargin/actions/workflows/ci.yml/badge.svg)](https://github.com/Southwall-Tester/LearnMargin/actions/workflows/ci.yml)\n\n把选定范围的课件、教材和笔记，变成带内容总览、详细讲解、例题与学习侧栏的 PDF。\n\nLearnMargin 提供两个独立产品，共用按《学习之道》18 章整理的方法参考：\n\n| 产品 | 使用方式 | 是否需要另配 API |\n|---|---|---|\n| [LearnMargin Skill](skills/learnmargin/USAGE.md) | 在现有 AI 会话中提供技能包、材料与范围，让 AI 直接生成 PDF | 不需要；由当前会话的 AI 和文档工具执行 |\n| LearnMargin 软件 | 本地 Web 界面上传资料、生成讲义、来回查看来源 | 需要配置兼容模型 API；内置示例除外 |\n\n只有 AI 订阅、没有 API 的使用者，直接选择 Skill。Skill 不依赖安装软件或启动本地服务；软件也不要求用户先在 AI 客户端安装 Skill。两者可在同一仓库维护，但分别交付 `learnmargin-skill.zip` 与 Python 软件包。\n\n软件包与独立 Skill 包可从 [GitHub Releases](https://github.com/Southwall-Tester/LearnMargin/releases/latest) 下载；版本变化见 [更新记录](CHANGELOG.md)。\n\n## 直接使用 Skill\n\n取得整个 [`skills/learnmargin/`](skills/learnmargin) 文件夹或 `learnmargin-skill.zip`，交给能够读取附件并生成文件的 AI 会话。支持技能目录的客户端也可按其规则安装该文件夹；不支持原生技能安装时，提供整个包并要求读取 `SKILL.md` 和相关参考文件即可。\n\n例如：“按照 LearnMargin Skill，结合这份课本和 PPT，讲解 PPT 第 10～20 页，并参考课本相关内容。生成 A4 内侧栏 PDF，包含知识总览、详细讲解、少量学习提示、后置答案与休息安排。”\n\n技能自带方法库，不要求再提供《学习之道》原书；用户仍需提供要学习的材料。PDF 使用当前 AI 环境已有的文件生成工具制作，可选脚本的依赖见技能使用说明。\n\n## 软件使用流程\n\n1. 导入一份或多份材料，查看解析结果。\n2. 指定主材料的文件页码、幻灯片或章节范围，回查同文件其他位置的必要定义与前提，其余材料自动检索为参考；也可填写知识点，跨全部资料检索。页码模式可关闭主材料范围外回查。\n3. 选择模型、输出语言和版式，填写必要的学习需求。输出默认简体中文，也可选择其他语言或自定义，不随材料语言自动切换。\n4. 生成 PDF，预览、下载，或在网页阅读中查看原材料并返回原位置；导出 HTML 和 JSON 可继续编辑。\n\n模型根据材料内容、知识依赖和讲解需要决定章节数量、顺序与边界，无需手动指定章数。讲义先给实质性的知识总览，再讲清概念、条件与推导。侧栏只保留有帮助的提示，需要作答的提示有后置参考答案与双向跳转。休息点按理解、例题和练习的预计负荷组合安排，短任务可跨章节合并，不按页数或每章一条的方式插入。用时估计及依据保存在生成数据中，实际休息以计时和疲劳为准。\n\n同时提供课本和 PPT 时，讲义按知识点整合，注明每份资料怎么说、具体位置以及互补或差异。页码模式完整保留主材料的指定范围，其他文件仅补充相关内容；未找到相关内容会说明。PDF 保留关键解释，能独立阅读；网页的“查看原材料”打开对应页或章节，“返回讲义”回到原位置。\n\n证明或例题依赖前文定义时，默认回查同一文件范围外的必要前提，以参考来源补入讲义，不增加无关学习主题。正文在使用前解释定义、符号角色和依赖的结论；缩写全称未知但定义已有依据时，照常讲清定义，不猜全称。审校发现关键前提仍无法核验时，指出具体缺口并停止生成，不把缺少依据的证明交付为完整讲解。\n\n**A4 标准版**将正文和侧栏放在同一张 A4 内，适合打印与平板阅读；**电脑宽版**提供更多横向空间。两种版式都能在前端选择。\n\n题目与答案双向定位到具体卡片。新导出的 PDF 使用 125% 跳转缩放，避免继承整页适应后只看出翻页；Web 会突出显示目标。独立 Skill 的附栏脚本可调整跳转缩放。\n\n**手写与扫描讲义**：自动模式会对缺少可提取文字的图像页进行多模态转录；“手写讲义”模式会逐个图像单元识读文字与公式，即使页面带有印刷页脚。公式保留为 LaTeX，无法辨认处标记“待核对”。网页来源同时提供原图、识读文本和疑点；原文件不被覆盖。这个步骤需要模型支持图片，并会增加 API 调用。导出包保留 `transcription.json`，便于复核。真实笔迹小样本验证和开源 OCR 调研见[识读说明](docs/OCR.md)。\n\n## 本地启动\n\n需要 Python 3.11+、Node.js 22+ 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)。以下命令适用于 PowerShell、Bash：\n\n```shell\ngit clone https://github.com/Southwall-Tester/LearnMargin.git\ncd LearnMargin\nnpm --prefix frontend ci\nnpm --prefix frontend run build\nuv sync --frozen --extra dev\nuv run playwright install chromium\nuv run learnmargin --open\n```\n\n打开 **http://127.0.0.1:8765**。先点“体验内置示例”可检查 PDF 引擎；该示例是预先编写的内容，不调用模型。首次安装 Chromium 需要联网，PDF 渲染运行时不依赖 CDN。\n\nLinux 还需中文字体和 Chromium 系统依赖：\n\n```shell\nsudo apt-get update\nsudo apt-get install -y fonts-noto-cjk\nuv run playwright install --with-deps chromium\n```\n\nWindows 也可以在完成安装后运行根目录的 `Start-LearnMargin.cmd`。\n\n更新后先关闭旧服务，再重新启动；仅刷新页面不会更新后端。端口被占用时，启动器会提示处理旧服务，不打开旧页面。\n\n## 模型与密钥\n\n可从 DeepSeek、OpenAI 或兼容 API 预置开始，配置服务地址、模型名、密钥、视觉输入及 JSON 模式。\n\n在模型设置中点击“测试连接”，可用少量固定文本检查当前地址、协议、模型和密钥是否能返回结果。仅在点击时发送一次请求，不发送学习材料、不保存密钥，也不自动重试；服务商可能按其 API 计费。测试文本通过不代表图片或整份讲义生成一定成功。\n\n| 接口 | 可用于 |\n|---|---|\n| Chat Completions | DeepSeek、OpenAI，以及提供该兼容接口的服务或本机模型 |\n| Responses | 提供 Responses 协议的服务 |\n\n这表示协议兼容，不表示任意模型都支持图片或结构化输出。使用自定义模型时按其能力调整“视觉输入”和“JSON 模式”。不支持图片的模型无法处理纯扫描页。\n\n“单次请求超时”默认 180 秒，可调至 600 秒；它限制每次模型请求（含服务重试和读取响应），不是整份讲义的总时长。“思考设置”按服务地址、协议和模型 ID 显示已确认的原生档位或开关，不统一映射等级，也不自动切换模型。未知服务或模型仅使用“不指定”；此时不发送思考参数，使用服务本身的默认行为（包括 DeepSeek，不再隐式关闭思考）。切换连接配置会清除旧档位并提示，旧偏好中的不兼容档位也会提示重选。支持范围、官方依据和扩展方式见 [思考设置适配](docs/REASONING.md)。降低强度可能减少等待，也可能影响复杂推理质量；连接测试只验证短文本请求，不证明长文生成速度。\n\n扫描或手写材料每识读完一页就保存。保持已导入材料并重新生成时，会复用原图、文本、识读模式、服务地址、模型及思考设置均匹配的完整识读；调高超时不必重读已完成页。缓存不保存密钥，随对应导入材料删除。总览、检索主题和章节依据检查使用完整转录（含图表说明与疑点），避免再次集中发送全部扫描原图；各章讲解与审校仍附原图。未转录的图片仍发送，单个图像丰富章节仍可能耗时较长。\n\n失败信息会保留具体阶段；逐页识读还记录文件、位置和耗时。重新生成会重新规划和生成章节，当前只复用逐页识读，不是完整任务的断点恢复。\n\n浏览器输入的密钥只保留在当前页面和执行中的任务内，不写入浏览器存储、任务记录或导出文件。也可以复制 `.env.example` 为 `.env`，在本机填写；CLI 会加载它。`LEARNMARGIN_API_KEY` 只用于匹配 `LEARNMARGIN_BASE_URL` 的端点，DeepSeek 与 OpenAI 环境密钥也只用于各自配置的端点。\n\nAPI 地址不能携带账号、查询参数或片段，请把密钥填在独立字段。远程服务使用 HTTPS；本机 HTTP 请求不会继承环境代理，HTTPS 仍支持已配置的代理。单次模型响应最多 8 MiB，请求总时限包含重试与读取响应；网关应遵循 `Accept-Encoding: identity` 返回未压缩 JSON。\n\n材料先在本机解析；点击生成后，所选内容会发送到所配置的 API。知识点模式会分析全部勾选材料；页码模式会读取主材料指定范围，并分析其他勾选参考文件以检索相关内容。开启前提回查时，还会检索主材料范围外的内容，增加相应 API 请求。检索按完整单元分批进行，选出生成所需内容，并在导出包中保存检索位置与依据。修改配置和导入文件不会自动调用模型。\n\n## 材料支持\n\n| 材料 | 范围单位与处理方式 |\n|---|---|\n| PDF | 文件页码；抽取文字并保留逐页图像，支持视觉模型读取扫描页 |\n| PPTX | 幻灯片；文字、表格、图片与备注 |\n| DOCX | 标题与连续内容段；不把解析出的段落冒充打印页码 |\n| EPUB | 按阅读顺序的章节及内嵌图片 |\n| TXT / Markdown / HTML / CSV 等 | 按连续内容段；不会加载外部网页素材 |\n| PNG / JPEG / WebP / TIFF 等 | 图片或帧；需要视觉模型理解内容 |\n| DOC / PPT / ODT / ODP / RTF | 可选 LibreOffice 沙箱转换；需要本机启用及受支持的系统隔离 |\n\nPPTX 的复杂图表、公式、SmartArt，以及 DOCX 的浮动布局可能无法完整提取。对这些材料，可先导出 PDF 后导入。旧格式转换默认关闭，启用后也必须建立系统沙箱；失败时直接拒绝转换，没有普通进程回退。该开关不能通过上传请求打开。\n\nWindows 需要 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 盘、桌面或宿主网络。配置仅由这个显式命令执行，上传不会自动安装系统组件。\n\nLinux 需要系统 LibreOffice、Python 3 和 bubblewrap 0.9 或更高版本，并设置同一本机启用开关。每次转换只读挂载输入和必需运行库，临时写入使用限额内存文件系统。macOS 暂无此转换沙箱，请先导出 PDF。平台条件及实际验证见[安全说明](docs/SECURITY.md)。\n\n上传前先限制实际请求体，压缩包按实际解压流校验大小与 CRC；XML 的 DTD/实体声明在编码识别后拒绝。文档解析在独立子进程内执行，限制为 150 秒和 2 GiB，超时或取消时终止该任务的进程树。资源限制不能替代对原生解析器的系统沙箱；完整边界与验证记录见[安全说明](docs/SECURITY.md)。\n\n单文件最多 50 MB、一次最多 8 份材料。每次导入最多 300 个内容单元；主材料与相关参考内容合计最多 60 个单元、10 万文本字符和 40 张图片。过大的范围会要求缩小，不静默截掉教材。知识点或参考资料检索最多分析 300 个单元、40 万文本字符。\n\n分章后会检查各章是否拿到了必要依据，将后页或其他材料中的相关定义、完整结论分配给需要它的章节；各章尚未覆盖全部已选材料时，这会增加一次模型请求。检查记录保存在导出包的 `section-source-review.json` 中。\n\n讲义应补足课件省略的必要解释，讲清概念、结论的含义、条件和推理，区分材料原文与助教补充。正文生成后会再次对照本节材料审校前提、来源转述、重复内容和侧栏答案。模型识读与审校仍可能出错，尤其是模糊手写、涂改和相似数学符号；这些步骤不能保证识读或教学内容一定正确。\n\n## Skill 内容与打包\n\n技能的独立使用说明见 [`USAGE.md`](skills/learnmargin/USAGE.md)，智能体入口是 [`SKILL.md`](skills/learnmargin/SKILL.md)，参考资料入口是[全书方法地图](skills/learnmargin/references/book-map.md)。\n\n内置的是原创转述的方法摘要与应用设计，包含适用情境、学习动作和边界，不含完整电子书或用户教材。软件直接读取同一份方法库，先选相关章节再设计提示。修改通用学习规则时，同步更新 skill、应用生成规则与受影响的验证。\n\n```shell\nuv run python scripts/package_skill.py\n```\n\n独立技能包生成于 `dist/learnmargin-skill.zip`。\n\n## 开发与检查\n\n```shell\n# 后端\nuv run learnmargin\n# 另一个终端启动前端；代理到8765\nnpm --prefix frontend run dev\n\nuv run ruff check src tests scripts\nuv run pytest\nnpm --prefix frontend test\nnpm --prefix frontend run build\nuv run python scripts/check_skill.py\nuv run --with pymupdf python -m pytest -q tests/test_skill_sidebars.py\nuv run python -m build\nuv run python scripts/package_skill.py\nuv run python scripts/verify_package.py\n```\n\n真实浏览器端到端检查见 [`frontend/e2e/smoke.py`](frontend/e2e/smoke.py)，只用内置示例，不触发付费生成。需要显式验证真实 API 时：\n\n```shell\nuv run python scripts/smoke_api.py --live\nuv run python scripts/smoke_api.py --live --mode pages\n```\n\n这会把项目自编示例发送到当前 API，可能产生费用；记录保存在被 Git 忽略的 `artifacts/` 中。CI 不读取真实密钥或调用付费模型。\n\nCI 会运行 Python 检查与测试、前端测试和构建、技能检查、软件与技能打包，并在仓库外的独立环境安装 wheel、启动服务和生成无 API 示例。打包检查记录保存在 `artifacts/package-verification.json`。设计和接口见 [架构说明](docs/ARCHITECTURE.md)、[接口契约](docs/CONTRACT.md)，贡献流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。\n\n## 数据与部署\n\n服务默认仅绑定 `127.0.0.1`，定位为单用户本机应用。材料、生成任务与产物存放在系统的 LearnMargin 用户数据目录，可用 `LEARNMARGIN_DATA_DIR` 指定其他位置。任务元数据会保存；进程重启后，未完成任务标记为中断，不假装自动恢复 API 请求。\n\n暂不包含公网多用户认证、配额计费或云端隔离，不能把当前本地服务直接作为公共网站部署。\n\n服务拒绝非本机连接及跨站 API 请求，限制上传和连接测试并发；新生成的讲义 HTML 只允许内置脚本，PDF 渲染启用 Chromium 系统沙箱，无法启用时直接报错。已有讲义不会被静默改写，重新生成或导出后才会带上新的 HTML 安全策略。\n\n## 方法与接口来源\n\n- 学习方法：Barbara Oakley《学习之道》，详见[知识库来源与边界](skills/learnmargin/references/book-map.md)。\n- API：DeepSeek [接入文档](https://api-docs.deepseek.com/)、[视觉输入](https://api-docs.deepseek.com/guides/vision/)；OpenAI [结构化输出](https://developers.openai.com/api/docs/guides/structured-outputs)。\n- 数学排版：[KaTeX](https://katex.org/)，资源及 MIT 许可证随项目保存；字体和其他依赖依其各自许可证使用。\n\n项目代码采用 [MIT License](LICENSE)。\n"}