dsh-course-logic-extractor

「课程逻辑提取器」agent 预设的 dsh 插件版：读取一门课程/论文的资料（大纲、讲义、课件、字幕、习题、论文 PDF 等），还原它的设计逻辑——先教什么、后教什么、每个环节为什么放在那里、环节之间如何衔接，交付自洽的逻辑链分析报告 + 学习路线图 + 流程画布，让学习者在正式深入之前先看清全局。

安装后，预设 course-logic-extractor 会自动出现在 DSH 的预设选择器中，随插件分发到任何机器。

功能特性

• 三种输入模式：直接分析（给资料路径）· 论文模式（双视角：研究逻辑 + 学习逻辑）· 自主找资料（无资料时按学习需求走迭代确认制流程）
• 入口分流（意图理解）：按用户首条消息直接判断——给资料路径走标准流程、给学习需求（任何表达「想获得知识/技能/理解」的意图都算，不必出现「学」字，目的不是必要条件）走自主流程、两者都没给则先介绍本 agent 用法
• 自主找资料（迭代确认制）：阶段一确定能力点清单（多层树形结构：一级并列 + 从属子能力点；过大能力点分解至可学习可检验的叶子；叶子标注前置/后置依赖与掌握标准；依赖图必产）→ 阶段二确定资料清单（先问学习形态偏好：书籍自学/视频为主/AI 决定/其他；七列固定：覆盖能力点｜名称｜来源｜链接/位置｜形态｜价值评估｜状态）→ 资料落地（本地优先 → 网络下载 → 缺失由用户决断）；每阶段以用户明确表态「完全确定」为唯一出口，规划留档于 0-规划/
• 材料管线：PDF 渲染（MuPDF）→ OCR 转录（GLM-OCR）→ 质量对账 → 直出归档 → 优化稿可选（直出后主动询问用户是否需要；仅为便于 Obsidian 阅读的易读性增强，与其他产出物无关，不需要可直接读 PDF 原件）
• 交付物：逻辑链分析（七节 + frontmatter + 自检）· 学习路线图 · 流程图 canvas 集（1-报告/画布/）· 证据层 · 材料层（含质量报告）
• 工程保障：单元测试（node:test）、CI（GitHub Actions 自动跑测试 + tag 自动发 Release）

安装

dsh plugin --profile web add github:ShadowBruceMeaningLau/dsh-course-logic-extractor

重启 dsh web（或任何使用 agent presets 的界面）。新建会话时在预设选择器里选「课程逻辑提取器」即可。

OCR 密钥（必需，否则转录功能不可用）

OCR 走智谱 GLM-OCR（glm-ocr，专用端点 layout_parsing）。两种配置方式任选其一：

1. 环境变量：ZHIPU_API_KEY；或
2. 配置文件：~/.dsh/free-vision.json 增加字段 {"zhipuApiKey": "…"}

免费申请：https://open.bigmodel.cn 。缺密钥时技能会明确提示用户补充，不影响其余功能（盘点、纯文本资料分析、网页抓取等）。

工作原理

• 插件本体是一个极小的宿主半边：启动时把内置的预设目录（preset/course-logic-extractor/）幂等落盘到 DSH 的用户预设根 ~/.dsh/.agent-presets/，预设选择器随即发现它。
• 不覆盖你的本地修改：目标位置已存在没有 .dsh-plugin 标记的预设（比如你自己写的版本）时，插件不碰它；只有插件自己装过的副本才会在版本升级时更新。
• 预设组合（agent.cordis.yml）引用官方 @deepseek-ai/dsh-* 包（由宿主解析），技能根通过 baseUrl 相对解析——整个预设完全可移植，无需任何网络安装步骤（scripts/node_modules/mupdf 已随包提交）。

技能与脚本

预设自带一个隔离技能 course-logic-extract（方法论唯一权威来源），脚本全部有单元测试护航：

脚本	用途	依赖
pdfrender.mjs	PDF → 高清页面图（渲染 + OCR 线路）	mupdf（已随插件打包，无需安装）
dsocr2md.mjs	页面图/PDF → Markdown（GLM-OCR layout_parsing）	智谱 API（见上）
verify.mjs	转录质量对账（缺失页/空页/公式配对 → 质量报告）	无
combine.mjs	直出合并归档（公式转 Obsidian 语法）	无
stylevol/split.mjs	按章切分直出稿为分卷	无
stylevol/merge.mjs	分卷按序合并为成品	无
stylevol/check.mjs	分卷成品校验（一致性/结构/覆盖）	无
mermaid2canvas.mjs	报告 mermaid 流程图 → Obsidian .canvas（--index=N 支持多图）	无

卸载 / 更新

# 卸载插件
dsh plugin --profile web remove dsh-course-logic-extractor
# 插件卸载后预设目录仍在（它是自包含的），如需一并删除：
# 删除 ~/.dsh/.agent-presets/course-logic-extractor

# 更新插件后，插件自己安装过的预设副本会在下次启动时自动更新；
# 若预设目录是你自己编辑过的版本，插件不会覆盖。

目录结构

├── package.json        插件声明（dsh.bundle.patch）
├── cordis.patch.yml    宿主行挂载
├── lib/index.js        宿主半边：幂等落盘预设
└── preset/course-logic-extractor/
    ├── agent.cordis.yml   预设组合（agent-plane）
    ├── preset.yml         显示元数据
    └── skills/course-logic-extract/
        ├── SKILL.md       方法论（唯一权威）
        ├── USAGE.md       用户使用指南
        ├── styles.config.json  风格集配置（defaultStyle + styles）
        ├── styles/        排版风格样本（数学/工程/文科/论文）
        └── scripts/       配套脚本 + node_modules/mupdf（已打包）+ test/（单元测试）

交付目录约定（运行期产出，非仓库内容）

课程逻辑交付/<课程名>/
├── 0-规划/    自主找资料模式专属：能力点清单.md（树形，叶子带前置/后置/掌握标准）
│              · 能力点依赖图.canvas（必有）· 资料清单.md（七列，状态随落地更新）
├── 1-报告/    逻辑链分析.md（必有）· 学习路线图.md（默认）· <课程名>_参考风格优化版.md（可选）
│   └── 画布/  模块地图.canvas · 学习路线图.canvas 等全部流程图画布（必有）
├── 2-证据/    分块七要素/证据提取文件（有则归档）
└── 3-材料/    页面渲染/ · 逐页转录/ · 直出稿/ · 风格版分卷/ · 质量报告.md（仅资料经 OCR/转换时存在）

许可证

MIT，见 LICENSE。