deep-read-summarize 0.3.11 → 0.3.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +21 -0
- package/README.en.md +7 -16
- package/README.md +7 -16
- package/cordis.patch.yml +1 -1
- package/docs/RELEASE.md +2 -1
- package/package.json +3 -2
- package/skills/deep-read-summarize/SKILL.md +7 -5
- package/tests/index.test.js +1 -1
- package/workflow.js +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,27 @@
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
The format is based on [Keep a Changelog](https://keepachangelog.com/).
|
|
5
5
|
|
|
6
|
+
## [0.3.12] — 2026-10-10
|
|
7
|
+
|
|
8
|
+
本轮**没有运行时改动**:生成的笔记与 0.3.11 一致(工作流脚本 `RAW_SCRIPT` 逐位未变,改动前后比对解码脚本哈希相同)。改的是文档定位,以及一处**已验证事实**的同步。
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
|
|
12
|
+
- **定位改为「输出标准 Markdown」,不再自我限定为 Obsidian 工具**:正文本来就是通用 CommonMark(无 `[[双链]]`、无 callout、无 Dataview 内联字段),frontmatter 也是标准 YAML。现在 README ×2 / `SKILL.md` / `package.json` description 都如实这么说;技能目录的 `description`、`whenToUse` 与 `workflow.meta.whenToUse` 一并放开,让「要一份 Markdown 笔记」这类请求也能命中本技能。
|
|
13
|
+
- `package.json` keywords 新增 `markdown`,保留 `obsidian` 作为检索入口。
|
|
14
|
+
- **README 删除「dsh.so 生态」一节**(中英各一处)及安装段里指向它的引用。**只影响文档**:仓库的 `dsh-plugin` topic 与 `package.json` 的 `dsh` 字段都保留——后者承载 `bundle.patch`,是插件加载所必需,不能删。
|
|
15
|
+
- **「尚未在真实 macOS 上验证」改为「已验证」**:README ×2 的「支持平台」一节现在陈述**已在真实 macOS 上跑通一次完整的无字幕转写**(`uv` 自举 Python 3.12 → 装 faster-whisper → 下载模型 → 输出逐字稿,退出码 0)。这条声明此前一直如实写着「尚未验证」,只有拿到真机结果才改。
|
|
16
|
+
|
|
17
|
+
### Compatibility
|
|
18
|
+
|
|
19
|
+
- 无破坏性变更。**生成的笔记与 0.3.11 完全一致**:本轮仅动文档与元数据。
|
|
20
|
+
- frontmatter 仍是既有的 9 个键,未做增删。**已知的跨工具语义冲突依旧存在**:`aliases` 在 Hugo 中是 URL 重定向、`type` 在 Hugo 中是 layout 选择。按目标工具切换 frontmatter(如 `options.frontmatter: obsidian / generic / minimal`)属于后续工作,本轮未做。
|
|
21
|
+
|
|
22
|
+
### Verification boundary
|
|
23
|
+
|
|
24
|
+
- 本次真机验证覆盖:完整转写链路(自举 Python 3.12 → 装 faster-whisper → 下载模型 → CPU 推理出逐字稿)。
|
|
25
|
+
- 仍未端到端跑通:`uv` 的 CPython 镜像失效后「自动改直连 GitHub」的回退链路(单测覆盖了尝试序列,但本机已有 Python 3.12,无法强制一次真实下载来贯通)。
|
|
26
|
+
|
|
6
27
|
## [0.3.11] — 2026-10-05
|
|
7
28
|
|
|
8
29
|
文档与 CI 补强:**运行时行为与 0.3.10 完全一致**,没有任何解析器 / 脚本 / schema 改动。
|
package/README.en.md
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
|
|
10
10
|
> **⚠️ Most importantly: this is an "assisted deep-reading" tool, not a substitute for your own learning.** It helps you quickly extract, summarize, and structure what you read, but **real understanding, thinking, and critique must still come from you**. Always treat the original source as authoritative — do not mistake the generated notes for the learning itself.
|
|
11
11
|
|
|
12
|
-
A deep-reading workflow for DSH (DeepSeek Harness): feed it a book, a paper, a video link, or a web page, and it produces a structured Obsidian
|
|
12
|
+
A deep-reading workflow for DSH (DeepSeek Harness): feed it a book, a paper, a video link, or a web page, and it produces a structured Markdown note (YAML frontmatter — ready for Obsidian, Logseq, static-site content folders, or any Markdown editor).
|
|
13
13
|
|
|
14
14
|
Content is split into chunks, read in parallel by multiple sub-agents, then merged into a Markdown file with YAML frontmatter. Key conclusions carry citations to the original source, and a quality check runs before the final draft.
|
|
15
15
|
|
|
@@ -43,7 +43,7 @@ Content is split into chunks, read in parallel by multiple sub-agents, then merg
|
|
|
43
43
|
- Chunk count — and therefore sub-agent count — is enforced by `maxChunks` (a runaway plan blows the per-call time limit)
|
|
44
44
|
- Key citations must carry page/chapter/paragraph references to reduce fabrication
|
|
45
45
|
- Configuration errors abort immediately; a chunk that fails to parse is skipped and marked as a gap
|
|
46
|
-
- Output
|
|
46
|
+
- Output is **standard Markdown + YAML frontmatter**: the body is plain CommonMark (no wikilinks, no callouts), so Obsidian (with Dataview), Logseq, Jekyll / Hugo / Astro content folders and any Markdown editor can consume it directly
|
|
47
47
|
|
|
48
48
|
---
|
|
49
49
|
|
|
@@ -65,7 +65,7 @@ Wave 2 N sub-agents deep-read chunks in parallel (Map)
|
|
|
65
65
|
Wave 3 Merge draft + quality check (Reduce)
|
|
66
66
|
│
|
|
67
67
|
▼
|
|
68
|
-
|
|
68
|
+
Markdown note
|
|
69
69
|
```
|
|
70
70
|
|
|
71
71
|
Three waves, roughly N+2 sub-agents in total, where N is the number of chunks.
|
|
@@ -87,15 +87,6 @@ To change how an input type is handled, drop a parser with the same interface in
|
|
|
87
87
|
|
|
88
88
|
---
|
|
89
89
|
|
|
90
|
-
## dsh.so ecosystem
|
|
91
|
-
|
|
92
|
-
This repo carries the `dsh-plugin` topic and the `dsh` field in `package.json`, so it can be indexed by the dsh.so registry.
|
|
93
|
-
|
|
94
|
-
dsh.so listing requirements: a public repo, the `dsh-plugin` topic (or the dsh field), README install instructions, and an SPDX license (MIT).
|
|
95
|
-
After submission it is marked **Declared** (self-declared compatibility); if you actually use it and verify compatibility, report your results in the official Discussions — that is the only way to be promoted to **Verified**.
|
|
96
|
-
|
|
97
|
-
---
|
|
98
|
-
|
|
99
90
|
## Platform support
|
|
100
91
|
|
|
101
92
|
**Windows / macOS / Linux are equally supported** (since 0.3.9). The plugin itself only needs Node (which DSH ships); the extra tools each input type may use are installed per platform:
|
|
@@ -110,12 +101,12 @@ Further notes:
|
|
|
110
101
|
- Transcription is the **only** part that needs an extra toolchain, and all three platforms share one Node script and one command: `node scripts/transcribe.js --audio <file> --out <txt>`.
|
|
111
102
|
- Transcription runs on **CPU** by default, so Apple Silicon / Intel Macs and Linux need no CUDA; GPU support needs a CUDA runtime and `options.device: "auto"` will try it and fall back to CPU on failure.
|
|
112
103
|
- Cache location per platform: macOS `~/Library/Caches/deep-read-summarize`, Linux `$XDG_CACHE_HOME/deep-read-summarize`, Windows `%LOCALAPPDATA%\deep-read-summarize`.
|
|
113
|
-
- A full transcription has
|
|
104
|
+
- A **full transcription has been run successfully on real macOS hardware** (since 0.3.12): `uv` bootstraps Python 3.12, installs faster-whisper, downloads the model and writes the transcript — exit code 0. CI's `macos-latest` job separately covers platform path resolution and the whole test suite. If you hit an error on a Mac, please open an issue.
|
|
114
105
|
|
|
115
106
|
---
|
|
116
107
|
## Installation (DSH plugin)
|
|
117
108
|
|
|
118
|
-
deep-read-summarize is a DSH plugin installable via npm
|
|
109
|
+
deep-read-summarize is a DSH plugin installable via npm or locally:
|
|
119
110
|
|
|
120
111
|
```bash
|
|
121
112
|
# npm install (published to the registry, no third-party dependencies)
|
|
@@ -201,7 +192,7 @@ Pass this JSON to DSH's workflow tool:
|
|
|
201
192
|
"maxRetries": 0, // quality-check retries (default 0 = no retry; retrying is noticeably slower)
|
|
202
193
|
"requireCitations": true, // whether key conclusions must carry citations
|
|
203
194
|
"includeTimestamps": false,
|
|
204
|
-
"outputDir": "./output", // note output directory (can point at your Obsidian vault)
|
|
195
|
+
"outputDir": "./output", // note output directory (can point at your Obsidian vault or a static-site content folder)
|
|
205
196
|
"tempDir": "./.tmp" // temp file directory
|
|
206
197
|
}
|
|
207
198
|
}
|
|
@@ -216,7 +207,7 @@ Examples:
|
|
|
216
207
|
| Video | `https://youtube.com/watch?v=xxx` |
|
|
217
208
|
| Web page | `https://example.com/article` |
|
|
218
209
|
|
|
219
|
-
Notes are written to `options.outputDir` (default `./output`, can point at your Obsidian vault), with the filename taken from the content title.
|
|
210
|
+
Notes are written to `options.outputDir` (default `./output`, can point at your Obsidian vault or a static-site content folder), with the filename taken from the content title.
|
|
220
211
|
|
|
221
212
|
### Video: full transcript (subtitles first, auto-transcription when none)
|
|
222
213
|
|
package/README.md
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
|
|
10
10
|
> **⚠️ 最重要:本工具是「辅助精读」工具,不能代替自主学习。** 它帮你快速提取、归纳、结构化阅读内容,但**真正的理解、思考与批判仍需你自己完成**;请始终以原文为准,不要把它当作学习成果本身。
|
|
11
11
|
|
|
12
|
-
给 DSH(DeepSeek Harness
|
|
12
|
+
给 DSH(DeepSeek Harness)写的一个精读工作流:输入一本书、一篇论文、一个视频链接或网页,输出一份结构化的标准 Markdown 笔记(YAML frontmatter,可直接放进 Obsidian / Logseq / 静态站点内容目录 / 任意 Markdown 编辑器)。
|
|
13
13
|
|
|
14
14
|
内容会被拆成若干块,由多个子代理并行精读,再合并成一篇带 YAML frontmatter 的 Markdown。关键结论附原文出处,成稿前有一道质量校验。
|
|
15
15
|
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
- 分块计划与子代理数量受 `maxChunks` 强制约束(计划失控会顶穿单次调用时限)
|
|
44
44
|
- 关键引用必须标注页码/章节/段落,降低编造风险
|
|
45
45
|
- 配置错误直接报错终止;某块内容解析失败则跳过并标记缺口
|
|
46
|
-
-
|
|
46
|
+
- 输出**标准 Markdown + YAML frontmatter**:正文是通用 CommonMark(无双链、无 callout),Obsidian(配合 Dataview)、Logseq、Jekyll / Hugo / Astro 的内容目录、任意 Markdown 编辑器都能直接用
|
|
47
47
|
|
|
48
48
|
---
|
|
49
49
|
|
|
@@ -65,7 +65,7 @@
|
|
|
65
65
|
波次3 合并成稿 + 质量校验(Reduce)
|
|
66
66
|
│
|
|
67
67
|
▼
|
|
68
|
-
|
|
68
|
+
Markdown 笔记
|
|
69
69
|
```
|
|
70
70
|
|
|
71
71
|
三个波次,子代理总数约 N+2 个,N 是分块数。
|
|
@@ -87,15 +87,6 @@ workflow.js workflow 脚本本体(meta + script)
|
|
|
87
87
|
|
|
88
88
|
---
|
|
89
89
|
|
|
90
|
-
## dsh.so 生态
|
|
91
|
-
|
|
92
|
-
本仓库带 `dsh-plugin` topic 和 `package.json` 的 `dsh` 字段,可被 dsh.so 注册表索引。
|
|
93
|
-
|
|
94
|
-
dsh.so 收录要求:公开仓库、`dsh-plugin` topic(或 dsh 字段)、README 安装说明、SPDX 许可证(MIT)。
|
|
95
|
-
提交后标记为 **Declared**(自声明兼容);如果你实际使用并验证兼容,请在官方 Discussions 报告结果,这是唯一升 **Verified** 的途径。
|
|
96
|
-
|
|
97
|
-
---
|
|
98
|
-
|
|
99
90
|
## 支持平台
|
|
100
91
|
|
|
101
92
|
**Windows / macOS / Linux 同等支持**(0.3.9 起)。插件本身只依赖 Node(DSH 自带),各环节需要的额外工具按平台装:
|
|
@@ -110,12 +101,12 @@ dsh.so 收录要求:公开仓库、`dsh-plugin` topic(或 dsh 字段)、RE
|
|
|
110
101
|
- 转写是**唯一**需要额外工具链的环节,三平台共用同一份 Node 脚本、同一条命令:`node scripts/transcribe.js --audio <音频> --out <txt>`。
|
|
111
102
|
- 转写默认走 **CPU**,Apple Silicon / Intel Mac 与 Linux 都不需要 CUDA;GPU 需自备 CUDA 运行库,`options.device: "auto"` 会尝试并在失败时自动回退 CPU。
|
|
112
103
|
- 缓存目录按平台取:macOS `~/Library/Caches/deep-read-summarize`、Linux `$XDG_CACHE_HOME/deep-read-summarize`、Windows `%LOCALAPPDATA%\deep-read-summarize`。
|
|
113
|
-
-
|
|
104
|
+
- 已在**真实 macOS** 上跑通一次完整的无字幕转写(0.3.12 起):`uv` 自举 Python 3.12 → 装 faster-whisper → 下载模型 → 输出逐字稿,退出码 0;CI 的 `macos-latest` 作业另外覆盖平台路径解析与整套测试。遇到报错欢迎开 issue 反馈。
|
|
114
105
|
|
|
115
106
|
---
|
|
116
107
|
## 安装(DSH 插件)
|
|
117
108
|
|
|
118
|
-
deep-read-summarize 是 DSH 插件,可通过 npm
|
|
109
|
+
deep-read-summarize 是 DSH 插件,可通过 npm 或本地安装:
|
|
119
110
|
|
|
120
111
|
```bash
|
|
121
112
|
# npm 安装(已发布到 registry,无第三方依赖)
|
|
@@ -201,7 +192,7 @@ parsers: book, paper, video, web
|
|
|
201
192
|
"maxRetries": 0, // 质量校验重试次数(默认 0 = 不重试,重试会明显变慢)
|
|
202
193
|
"requireCitations": true, // 关键结论是否必须标注出处
|
|
203
194
|
"includeTimestamps": false,
|
|
204
|
-
"outputDir": "./output", // 笔记输出目录(可指向 Obsidian
|
|
195
|
+
"outputDir": "./output", // 笔记输出目录(可指向 Obsidian 仓库或静态站点内容目录)
|
|
205
196
|
"tempDir": "./.tmp" // 临时文件目录
|
|
206
197
|
}
|
|
207
198
|
}
|
|
@@ -216,7 +207,7 @@ parsers: book, paper, video, web
|
|
|
216
207
|
| 视频 | `https://youtube.com/watch?v=xxx` |
|
|
217
208
|
| 网页 | `https://example.com/article` |
|
|
218
209
|
|
|
219
|
-
笔记写到 `options.outputDir` 指定的目录(默认 `./output`,可指向你的 Obsidian
|
|
210
|
+
笔记写到 `options.outputDir` 指定的目录(默认 `./output`,可指向你的 Obsidian 仓库或静态站点内容目录),文件名取自内容标题。
|
|
220
211
|
|
|
221
212
|
### 视频:完整逐字稿(字幕优先,无字幕自动转写)
|
|
222
213
|
|
package/cordis.patch.yml
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
#
|
|
5
5
|
# This plugin is a workflow + skill provider: it registers the deep-read-summarize
|
|
6
6
|
# workflow (meta/script) and the filesystem skill, so users can deep-read books,
|
|
7
|
-
# papers, videos and web pages into structured
|
|
7
|
+
# papers, videos and web pages into structured Markdown notes.
|
|
8
8
|
|
|
9
9
|
- insert:
|
|
10
10
|
- id: deep-read-summarize
|
package/docs/RELEASE.md
CHANGED
|
@@ -112,7 +112,8 @@ npm view deep-read-summarize --prefer-online # 验证线
|
|
|
112
112
|
| v0.3.8 | **仅 GitHub** | 打了 tag 与 Release 但漏发到 npm(Trusted Publishing 迁移期的缺口;修复已随 0.3.9 交付) |
|
|
113
113
|
| v0.3.9 | npm 已发布 | macOS / Linux 支持(转写链路跨平台) |
|
|
114
114
|
| v0.3.10 | npm 已发布 | 修:失效的 uv 镜像、空转写被当成成功、发布文档过时 |
|
|
115
|
-
|
|
|
115
|
+
| v0.3.11 | npm 已发布 | 文档:README 补「支持平台」;CI:三平台跑全套门禁 |
|
|
116
|
+
| **v0.3.12** | **npm 已发布(当前)** | 文档:定位改为「标准 Markdown」;删 dsh.so 一节;macOS 真机验证转写通过 |
|
|
116
117
|
| v1.0.0 | 计划 | API 稳定后发布 |
|
|
117
118
|
|
|
118
119
|
> 早期迭代用 0.x 表达不稳定;API 稳定后再发 1.0.0。
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "deep-read-summarize",
|
|
3
|
-
"version": "0.3.
|
|
4
|
-
"description": "Deep reading & summarization for DSH: books/papers/videos/web → structured Obsidian
|
|
3
|
+
"version": "0.3.12",
|
|
4
|
+
"description": "Deep reading & summarization for DSH: books/papers/videos/web → structured Markdown notes (Obsidian / Logseq / static sites). Plugin parsers, MapReduce deep-read, JSON Schema-constrained sub-tasks.",
|
|
5
5
|
"type": "commonjs",
|
|
6
6
|
"main": "index.js",
|
|
7
7
|
"exports": {
|
|
@@ -52,6 +52,7 @@
|
|
|
52
52
|
"summarization",
|
|
53
53
|
"deep-read",
|
|
54
54
|
"obsidian",
|
|
55
|
+
"markdown",
|
|
55
56
|
"llm",
|
|
56
57
|
"subagent",
|
|
57
58
|
"mapreduce",
|
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: deep-read-summarize
|
|
3
|
-
description: 深度精读并总结书籍/学术论文/视频/网页,输出带 YAML frontmatter
|
|
4
|
-
whenToUse: 用户提供一本书、论文(arXiv/PDF)、视频链接(YouTube/B
|
|
3
|
+
description: 深度精读并总结书籍/学术论文/视频/网页,输出带 YAML frontmatter 的标准 Markdown 笔记(2500+ 字,含术语表/批判分析/行动要点/延伸阅读;可直接放进 Obsidian / Logseq / 静态站点内容目录)
|
|
4
|
+
whenToUse: 用户提供一本书、论文(arXiv/PDF)、视频链接(YouTube/B站)或网页,要求深度精读、提取要点、生成可保存的 Markdown 精读笔记时(Obsidian / Logseq 仓库、静态站点内容目录、任意 Markdown 编辑器均可)
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# deep-read-summarize — 深度精读与总结
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
把一本书、一篇论文、一个视频或网页,精读成一篇结构化的标准 Markdown 笔记。
|
|
10
|
+
|
|
11
|
+
正文是通用 CommonMark(**无双链、无 callout、无编辑器专属语法**),所以 Obsidian(配合 Dataview)、Logseq、Jekyll / Hugo / Astro 的内容目录,以及任意 Markdown 编辑器都能直接使用。
|
|
10
12
|
|
|
11
13
|
## 能力
|
|
12
14
|
|
|
@@ -16,7 +18,7 @@ whenToUse: 用户提供一本书、论文(arXiv/PDF)、视频链接(YouTub
|
|
|
16
18
|
- 分块计划与子代理数量受 `maxChunks` 强制约束(计划失控会顶穿单次调用时限)
|
|
17
19
|
- 关键引用标注页码/章节/段落,降低编造风险
|
|
18
20
|
- 配置错误终止(FATAL);内容解析失败降级标记缺口继续
|
|
19
|
-
-
|
|
21
|
+
- 输出**标准 Markdown + YAML frontmatter**:正文为通用 CommonMark,frontmatter 的 `type` 字段可配 Dataview 查询
|
|
20
22
|
|
|
21
23
|
## 输入
|
|
22
24
|
|
|
@@ -39,7 +41,7 @@ whenToUse: 用户提供一本书、论文(arXiv/PDF)、视频链接(YouTub
|
|
|
39
41
|
|
|
40
42
|
workflow 返回 `{ ok, filePath, note, qualityPassed, qualityIssues, failedChunks, textSource }`。
|
|
41
43
|
|
|
42
|
-
> ⚠️ **`note` 就是完整笔记正文,`filePath` 只是建议路径**:脚本运行在无文件系统的沙箱里(DSH 的 workflow 契约:脚本只负责协调子代理),**它不会替你写文件**。必须由你(主代理)在拿到结果后用 `write` 工具把它写到 `filePath`——默认 `./output/`,可用 `options.outputDir` 指向 Obsidian
|
|
44
|
+
> ⚠️ **`note` 就是完整笔记正文,`filePath` 只是建议路径**:脚本运行在无文件系统的沙箱里(DSH 的 workflow 契约:脚本只负责协调子代理),**它不会替你写文件**。必须由你(主代理)在拿到结果后用 `write` 工具把它写到 `filePath`——默认 `./output/`,可用 `options.outputDir` 指向 Obsidian 仓库或静态站点的内容目录。
|
|
43
45
|
|
|
44
46
|
```markdown
|
|
45
47
|
---
|
package/tests/index.test.js
CHANGED
package/workflow.js
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
const meta = {
|
|
10
10
|
"name": "deep-read-summarize",
|
|
11
11
|
"description": "Deep reading & summarization of books/papers/videos/web (v3.0)",
|
|
12
|
-
"whenToUse": "User provides a book, paper, video link or web page and wants a deep-read summary saved
|
|
12
|
+
"whenToUse": "User provides a book, paper, video link or web page and wants a deep-read summary saved as a Markdown note",
|
|
13
13
|
"phases": [
|
|
14
14
|
{
|
|
15
15
|
"title": "解析器选择",
|