前言¶
在 DeepSeek Harness (DSH) 的插件生态中，扩展宿主能力的主要方式是安装社区插件。面对一门课程或一篇论文的资料，单纯阅读大纲和课件往往难以快速提炼出其设计逻辑——即“先教什么、后教什么”，以及每个环节“为什么放在那里”和“环节之间如何衔接”。
dsh-course-logic-extractor 插件旨在解决这个问题。它读取课程或论文的资料（大纲、讲义、课件、PDF 等），通过算法还原其设计逻辑，最终交付一份自洽的逻辑链分析报告、学习路线图以及流程画布。这能帮助学习者在正式深入内容之前先看清全局。
安装与启用¶
安装插件需要执行一条命令。安装完成后，插件会自动将预设分发到本地。
- 执行安装命令：
dsh plugin --profile web add github:ShadowBruceMeaningLau/dsh-course-logic-extractor
- 重启
dsh web（或任何使用 agent presets 的界面）。 - 新建会话时，在预设选择器里选择「课程逻辑提取器」即可使用。
核心功能¶
该插件提供了三种输入模式，并内置了意图识别和迭代确认机制。
三种输入模式¶
- 直接分析：直接提供资料路径，进行标准逻辑提取。
- 论文模式：双视角分析，兼顾研究逻辑与学习逻辑。
- 自主找资料：当没有资料时，按学习需求走迭代确认制流程。
入口分流（意图理解）¶
插件会分析用户的首条消息。根据消息内容自动分流：
* 给出资料路径：走标准流程。
* 表达学习需求（任何表达“想获得知识/技能/理解”的意图都算）：走自主流程。
* 未提供任何信息：先介绍本 agent 的用法。
自主找资料（迭代确认制）¶
在无资料模式下，流程分为两个阶段，每阶段以用户明确表态“完全确定”为唯一出口。
- 阶段一：确定能力点清单
构建多层树形结构。一级并列能力点下包含从属子能力点。将过大能力点分解为可学习、可检验的叶子节点，并标注前置/后置依赖与掌握标准。必须产出能力点依赖图。 - 阶段二：确定资料清单
先确认学习形态偏好（书籍自学/视频为主/AI 决定/其他）。
生成固定七列清单：覆盖能力点、名称、来源、链接/位置、形态、价值评估、状态。
资料落地顺序为：本地优先 → 网络下载 → 缺失由用户决断。
规划内容留档于0-规划/目录。
材料管线¶
当处理 PDF 等非文本资料时，插件会启动以下管线：
1. PDF 渲染：使用内置 MuPDF（已打包，无需网络安装）将 PDF 渲染为高清页面图。
2. OCR 转录：调用智谱 GLM-OCR 的 layout_parsing 接口进行转录。
3. 质量对账：检查缺失页、空页、公式配对等问题，生成质量报告。
4. 直出归档：合并转录内容，归档至交付目录。
5. 优化稿（可选）：在直出后询问用户是否需要，生成便于 Obsidian 阅读的优化版（与其他产出物无关）。
交付物¶
插件最终交付以下内容：
* 逻辑链分析：包含七节内容、frontmatter 和自检报告。
* 学习路线图：指导学习路径。
* 流程图画布集：生成 Obsidian .canvas 文件，包括模块地图、学习路线图等。
* 证据层与材料层：包含分块七要素的证据提取文件和材料归档。
配置与注意事项¶
OCR 密钥配置¶
转录功能依赖智谱 GLM-OCR，需要配置密钥。若未配置，转录功能不可用，但不影响其他功能（如盘点、纯文本分析）。
支持两种配置方式：
1. 环境变量：ZHIPU_API_KEY。
2. 配置文件：在 ~/.dsh/free-vision.json 中增加字段 {"zhipuApiKey": "…"}。
本地修改保护¶
插件具有幂等性。如果目标位置已存在没有 .dsh-plugin 标记的预设（例如你自己写的版本），插件不会覆盖它。只有插件自己安装过的副本才会在版本升级时更新。
可移植性¶
插件本体包含必要的依赖（如 node_modules/mupdf），无需网络安装步骤。整个预设通过相对路径引用官方包，完全可移植。
目录结构与交付物¶
插件目录结构¶
插件安装后，其本体包含以下结构：
* package.json：插件声明。
* cordis.patch.yml：宿主行挂载配置。
* lib/index.js：宿主半边，负责幂等落盘预设。
* preset/course-logic-extractor/：包含预设组合文件和技能目录。
运行时交付目录¶
运行时会在当前目录下生成 课程逻辑交付/<课程名>/ 目录，包含：
* 0-规划/：能力点清单、依赖图、资料清单。
* 1-报告/：逻辑链分析、学习路线图、画布集。
* 2-证据/：证据提取文件。
* 3-材料/：页面渲染图、转录稿、直出稿、质量报告。
