deep-read-summarize 0.3.6 → 0.3.9

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 CHANGED
@@ -3,6 +3,102 @@
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.9] — 2026-09-22
7
+
8
+ **macOS / Linux 支持**。这一版补上最后一块 Windows-only 的拼图:此前「无字幕视频自动转写」依赖 `scripts/transcribe.ps1`(PowerShell),SKILL.md 里明确写着「**目前仅在 Windows 可用**」;现在换成跨平台的 Node 脚本,三平台同一份实现、同一条命令。
9
+
10
+ ### Added
11
+
12
+ - **`scripts/transcribe.js` 取代 `scripts/transcribe.ps1`**:跨平台转写自举脚本(Windows / macOS / Linux)。平台差异只集中在四个纯函数里(`cacheRoot` / `venvPython` / `uvInstallHint` / `findUv`),它们都接受注入的 `platform/env/home`——因此**任意 OS 上都能跑全平台矩阵单测**,不必依赖 macOS 机器。
13
+ - 缓存目录:Windows `%LOCALAPPDATA%\deep-read-summarize`、macOS `~/Library/Caches/deep-read-summarize`、Linux `$XDG_CACHE_HOME/deep-read-summarize`
14
+ - uv 探测:先扫 PATH,再回退 `~/.local/bin`、`/opt/homebrew/bin`、`/usr/local/bin`、`~/.cargo/bin`(macOS 从图形界面启动时不继承 shell PATH,这一步是必需的);找不到时按平台给出安装命令(winget / brew / curl 安装器)
15
+ - `--self-check`:只打印解析出的路径,不安装、不下载、不联网——CI 三平台用它做冒烟
16
+ - **`options.device` 选项**(默认 `cpu`,可选 `auto`/`cuda`):从 options → workflow 脚本 → 解析器 → 命令行全程打通(与 `whisperModel` / `language` 同一条路径),不是写死在提示词里。`auto`/`cuda` 需自备 CUDA 运行库,失败自动回退 CPU。
17
+ - **CI 新增 `cross-platform` 作业**:在 ubuntu / macos / windows 三个 runner 上跑 lint + `--self-check`,真正在 macOS 上执行一遍平台分支。
18
+
19
+ ### Fixed
20
+
21
+ - **`device='auto'` 在「有 NVIDIA 显卡但没装 CUDA 运行库」的机器上必崩(真机复现)**:ctranslate2 只要探测到显卡(`get_cuda_device_count() == 1`)就会在 `auto` 下选 CUDA,随后在推理时抛 `Library cublas64_12.dll is not found or cannot be loaded`。这是 0.3.6 起就潜伏在 `transcribe.ps1` 里的问题(本机 RTX 3050 复现)。现在默认 `device=cpu`(与 README 承诺的「CPU 友好、零额外依赖」一致);设 `options.device: "auto"` 时,失败也会**自动回退 CPU 并打印原因**。
22
+ - **转写中途失败会留下半截 `transcript.txt`**:调用方(提示词第 ④ 步)是按「输出文件非空且稳定」判断转写完成的,半截文件会被**误判成成功**。现在先在内存里收集全部分段,成功后才落盘。
23
+ - **`parsers/video.js` 提示词里的 PowerShell 路径少了分隔符**:`$env:USERPROFILE\.dsh` 写在 JS 字符串里,`\.` 被当成未知转义退化成 `.`,实际发出去的提示词是 `$env:USERPROFILE.dsh`。改用正斜杠(PowerShell 同样接受)。
24
+ - **`parsers/book.js` 让代理用 `pwsh` 调 pdftotext**(第二轮全仓复查才发现,第一轮只盯着转写链路):macOS 默认没有 PowerShell,**书籍/PDF 这条路在 macOS 上会直接卡住**。现在改成平台中立的 pdftotext 说明,并给出三平台安装方式(macOS `brew install poppler` / Windows `winget install poppler` / Debian·Ubuntu `apt install poppler-utils`)。
25
+ - **`--out` 的父目录不存在时失败信息难以理解**:现在脚本自己先把父目录建好(`./.tmp` 这类调用方路径),不再让 python 抛一句难懂的 `No such file or directory`。
26
+
27
+ ### Changed
28
+
29
+ - **`parsers/video.js` 提示词改为平台中立**:同时给出 Windows 与 macOS/Linux 的脚本定位命令(`Get-ChildItem … -Filter transcribe.js` / `find "$HOME/.dsh" -name transcribe.js`),yt-dlp 安装同时给出 `winget` 与 `brew`;转写命令三平台统一为 `node <脚本路径> --audio … --out … --device cpu --model … --language …`。
30
+ - 提示词**不能**按平台分支:它会被内联进 workflow 沙箱脚本,而沙箱不提供 `process`(`tests/run-tests.js` 有对应断言),所以两套写法都写出来、由执行代理按自己的系统选。
31
+ - 转写输出不再带结尾空格(改用 `' '.join(...)`)。
32
+ - 提示词里「转写执行」的 ①–⑥ 子步骤此前被模板编号成了一个独立的顶层步骤(`7. ① 先取音频…`,后续行反而没有编号),现在与标题合并为同一步,编号回到 `6. 转写执行(…):` + 未编号的 ①–⑥。
33
+ - `README.md` / `README.en.md` / `SKILL.md` 同步:删掉「仅 Windows 可用」,补上跨平台命令、平台缓存目录与 `options.device` 说明。
34
+
35
+ ### Compatibility
36
+
37
+ - **Windows 用户零迁移成本**:缓存目录与 `transcribe.ps1` 逐字一致,**已下载的模型不会重下**(真机验证:复用既有 venv + 模型,未触发下载)。
38
+ - 唯一入口改名 `transcribe.ps1` → `transcribe.js`;提示词文本随之变化(脚本名、参数形式、`options.device`),依赖提示词逐字比对的 fork 需要同步。
39
+ - 转写默认从 `auto` 变为 `cpu`:原 `auto` 在无 CUDA 运行库的机器上本来就会崩,真正的 GPU 用户可显式传 `--device auto`。
40
+
41
+ ## [0.3.8] — 2026-09-16
42
+
43
+ 又一次「代码审查 + 真机复现」驱动的修复轮。这一轮的核心发现不是某一行写错了,而是**几处「文档承诺」与「代码实际行为」对不上**:选项算出来不用、schema 抄了两份各自漂移、配置文件里的键全是空转。所有 P0 都用 mock 掉 `agent/parallel/phase/log` 的方式**跑真实脚本复现过**,并各自补了回归测试。测试 35 → **62**(fixture 35 + node:test 27)。
44
+
45
+ ### Fixed
46
+
47
+ - **frontmatter 注入:标题里带引号会产出坏 YAML(P0)**。`title: "《" + finalTitle + "》…"` 是裸拼,内容标题含 `"`(如 *The "Best" Method*)时 frontmatter 直接被截断,Obsidian / Dataview 全部解析失败。现在统一走 `yamlStr()`(JSON 字符串转义,是 YAML double-quoted 风格的子集),`title / aliases / author / year / type / url` 全部转义;标题里的换行/制表也一并折叠,不再污染 `.md` 文件名。
48
+ - **幂等命中分支会返回空笔记(P0)**。脚本里那段 `args._processedKeys` 早返回,命中时返回 `note: ""` + `filePath: ""`;而 SKILL.md 第 8 步要求主代理「把 `note` 写入 `filePath`」——命中即写出空文件。宿主实际上**从不注入 `args._processedKeys`**(0.1.x 全仓 0 命中),这段代码永远不会命中,一旦命中就是数据事故。整段删除。
49
+ - **分块计划不受 `maxChunks` 约束(P0)**。提示词里写着「块数不超过 N 块」,但脚本原样相信子代理返回的 `chunkPlan`:实测 `maxChunks: 4` 会起 **10 个子代理**——这正是 0.3.x 反复踩的「单次调用超时」的成因。现在按上限截断,并在收敛时记日志。
50
+ - **分块行号区间不校验(P0)**。倒置区间(`startLine: 900, endLine: 100`)会原样拼成 `limit=-799` 交给 `read`。现在丢弃倒置/越界的块,并按 `totalLines` 夹紧上界;全部无效时按可降级错误返回,不再空跑。
51
+ - **全非法字符的标题会写出隐藏文件**:`///` 之类清洗后为空 → `./output/.md`。现在兜底为 `未命名内容.md`。
52
+ - **`options.transcribe: false` 完全无效**。`parsers/video.js` 里 `wantTranscribe` 算完从未被使用,`true` 与 `false` 生成的提示词**逐字相同**,README/SKILL 却都承诺「false 则跳过转写」。现在提示词真的分流:禁用时明确禁止定位/运行 `transcribe.ps1`、禁止下载模型,直接走降级。
53
+ - **`options.whisperModel` / `options.language` 文档教用、代码没有**。README 写着「可用 `options.whisperModel` 调整」「纯英文视频可设 `language: "en"`」,但脚本既不读也不透传,转写命令里 `-Model small -Language zh` 是写死的。现在两个选项都从 options → 脚本 → 解析器 → 命令行全程打通,默认值保持 `small` / `zh`(对既有用户零行为变化)。
54
+ - **`kind` 会变成 `"auto"` 流进笔记**。`type: auto` 且子代理没回 `kind` 时,`frontmatter` 的 `type` 与 `tags` 会被写成 `auto`。现在 `auto` 只接受解析器表里真实存在的类型,否则退回实际使用的回退解析器。
55
+
56
+ ### Changed
57
+
58
+ - **插件 config 不再是空转**。`apply(ctx, config)` 此前收了 config 从不读它,`cordis.patch.yml` 里列的 8 个键(`outputDir`/`tempDir`/`minWords`/…)全部无效。现在会做白名单校验(类型不符 → 告警并忽略,不会因为一个拼错的键把整个 profile 拖死),合并进技能里的 args 示例,成为该 profile 的默认值。`cordis.patch.yml` 的注释同步改写(含 `maxChunks` 6 → 4)。
59
+ - **schema 不再有两份真相**。脚本里那份手抄的 `fetchSchema` 已删除,改由 `workflow.js` 在构建自包含脚本时从 `schemas/index.js` **注入**;`kind` 的 `enum` 跟着解析器注册表走。此前手抄副本已经漂移(丢了 `enum`)。同时把 `chunkReadSchema` / `qualityChecklistSchema` **没有被 workflow 使用**这件事写进 `schemas/index.js` 头部——它们留给程序化调用方。
60
+ - **自定义解析器真正可用**。以前 `type` 白名单写死 `auto|book|paper|video|web`,且自包含脚本只内联这四个,`custom-parsers/` 里的**新类型**端到端不可达。现在内联的是注册表里的全部解析器,白名单与 schema 枚举都从注册表推导;同名覆盖照旧有效。
61
+ - **幂等从「脚本假装会做」改成「文档如实说不会做」**。脚本沙箱没有文件系统,写不了指纹记录——`lib/cache.js` 从 0.1.0 起就没被 workflow 调用过。现在 SKILL.md 第 2 步改为:由主代理在落盘前检查目标 `filePath` 是否已存在;程序化去重可用 `deep-read-summarize/lib/cache`(`package.json` 的 `exports` 补上了这个子路径,此前被 exports map 挡住根本 require 不到)。
62
+ - SKILL.md 新增第 9 步:`ok: false` 要说明卡在哪一步,`qualityPassed: false` / `failedChunks > 0` 必须在回复里点出来,不许拿半成品冒充成品。
63
+ - `prepublishOnly` 补跑 `node --test`(此前发布门禁只跑 fixture 测试,`tests/index.test.js` 不在门禁内)。
64
+ - npm 描述去掉 `idempotent cache`(工作流层确实没有这个能力)。
65
+
66
+ ### Added
67
+
68
+ - **workflow 运行时回归测试(12 → 27 项 `node:test`)**:用 mock 掉 `agent/parallel/phase/log` 的方式跑**真实脚本**,逐条锁住本轮修的 P0/P1——分块收敛、区间夹紧、全无效计划降级、YAML 转义、隐藏文件名兜底、`kind` 兜底、幂等早返回已移除、`transcribe` 分流、`whisperModel`/`language` 透传、config 校验与透传、schema 单一真相、自定义类型端到端(含自定义解析器内联与枚举跟进)、未知类型仍然响亮报错、`lib/cache` 可达。
69
+
70
+ ### Compatibility
71
+
72
+ - 对既有用户**无破坏性变更**:默认值全部保持不变(`maxChunks` 4、`transcribe` true、`whisperModel` small、`language` zh、`outputDir` `./output`)。
73
+ - 行为变化仅在于「以前被静默忽略的东西现在生效了」:超过 `maxChunks` 的计划会被截断(子代理数下降、耗时下降)、非法分块区间会被丢弃(此前会把负数 limit 传给 `read`)。
74
+ - 历史文档 `docs/RELEASE-v0.1.0.md` 里 v0.1.0 的「幂等缓存」描述保持原样(它是对当时意图的记录),实际能力以本节与 `schemas/index.js` 的说明为准。
75
+
76
+ ## [0.3.7] — 2026-09-09
77
+
78
+ 针对 **DSH 0.1.2-rc.1** 的一轮兼容性核查与打磨(对使用者无破坏性变更)。
79
+
80
+ ### Fixed
81
+
82
+ - **笔记落盘步骤缺失(最容易丢数据的一条)**:SKILL.md 写「默认写到 `./output/`」,但 DSH 的 workflow 契约规定脚本只能协调子代理——**沙箱内没有文件系统**,脚本实际只返回 `{ filePath, note }`。照原文档执行,模型会以为文件已经写好,笔记只存在于返回值里。现在 SKILL.md 新增明确的第 8 步「用 `write` 工具把 `note` 写入 `filePath`」,两版 README 同步说明。
83
+ - **`npm run test:node` 在 Node 24 上直接失败**:`node --test tests/` 在该版本会把 `tests/` 当模块解析(`MODULE_NOT_FOUND`)。改为 `node --test`(自动发现)。
84
+ - **CI 从不运行 `tests/index.test.js`**:里面正是 0.3.3 事故(入口缺 `apply()` → 宿主拒绝启动)的 Cordis 契约回归测试,却因为只在 `node --test` 下跑而从未被执行。CI 新增该步骤,矩阵补上 **Node 24**(宿主实际运行版本)。
85
+
86
+ ### Changed
87
+
88
+ - **npm 包不再携带 docs 截图**:`files` 由整个 `docs/` 收窄为两份 RELEASE 文档。0.3.6 发布之后仓库才提交的 4 张 showcase 图(合计约 1.14MB)会让下次发版的 tarball 从 99KB 涨到 1.1MB;现在回到约 100KB。图片仍随仓库分发,README 改用 GitHub 绝对地址引用(npm 页面照常显示),顺带把一直没有被任何文档引用的演示图补进 README。
89
+ - **技能 `source` 改为 `bundled`**:该字段是技能的「来源桶」(`runtime`/`bundled`/`user-dsh`…),此前填的是自由描述 `plugin:deep-read-summarize`。
90
+ - README/README.en.md 的「兼容性」节改写为:已验证宿主(DSH 0.1.2-rc.1)+ 依赖面表格 + 两条契约细节(沙箱无文件系统;违反 schema 子集是**终止**而非降级)。
91
+ - `.gitignore` 增加 `*.tgz`(本地 pack 产物不再出现在 `git status`)。
92
+
93
+ ### Added
94
+
95
+ - **workflow 契约回归测试(零依赖)**:schema 子集递归校验(含反向断言,确保校验器不会空放行)、`agent()` 选项白名单、沙箱禁用 API(`require`/`fs`/`process`/`fetch`/定时器)扫描、脚本四解析器自包含、技能内容包含 meta + script + args 与落盘步骤、插件 Cordis 契约 + 技能登记行为。测试 28 → **35**。
96
+
97
+ ### Compatibility
98
+
99
+ - 实测证据(0.1.2-rc.1):两个 `agent()` schema 用宿主真实的 `assertObjectJsonSchema` 校验**通过**,对照用例 `minLength` 被拒(证明校验器有效、不是空放行);脚本只使用 `agent/parallel/phase/log/args`;`agent()` 失败返回 `null` 已被脚本正确处理。
100
+ - 未改动 workflow 脚本本身与解析器行为;本次修复集中在「落盘契约、测试与 CI、打包体积、文档准确性」。
101
+
6
102
  ## [0.3.6] — 2026-08-28
7
103
 
8
104
  ### Added
@@ -141,4 +237,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
141
237
  ### Added
142
238
  - Initial deep-reading pipeline (5 serial waves)
143
239
  - Template prompts for books/papers/videos/web
144
- - Obsidian note template with YAML frontmatter
240
+ - Obsidian note template with YAML frontmatter
package/README.en.md ADDED
@@ -0,0 +1,314 @@
1
+ # deep-read-summarize
2
+
3
+ [![MIT license](https://img.shields.io/github/license/PensiveFei/deep-read-summarize)](https://github.com/PensiveFei/deep-read-summarize/blob/main/LICENSE)
4
+ [![release](https://img.shields.io/github/v/release/PensiveFei/deep-read-summarize)](https://github.com/PensiveFei/deep-read-summarize/releases)
5
+ [![CI](https://img.shields.io/github/actions/workflow/status/PensiveFei/deep-read-summarize/ci.yml)](https://github.com/PensiveFei/deep-read-summarize/actions/workflows/ci.yml)
6
+ [![npm downloads](https://badgen.net/npm/dm/deep-read-summarize)](https://www.npmjs.com/package/deep-read-summarize)
7
+
8
+ > **Disclaimer**: This is an **unofficial third-party tool**. It is not affiliated with, endorsed by, or sponsored by DeepSeek or the DeepSeek Harness project. "DeepSeek" and "DeepSeek Harness" are trademarks of their respective owners. This project only orchestrates the workflow tool available in your DSH environment; it does not redistribute any DeepSeek software.
9
+
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
+
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 note.
13
+
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
+
16
+ > If you run into problems, or see how it could be better, **feel free to open a GitHub issue**.
17
+
18
+ > Note: DSH is currently a developer preview and its interfaces may change. This repo targets a specific version of the workflow-tool semantics — see [Compatibility](#compatibility).
19
+
20
+ ---
21
+
22
+ ## What it looks like
23
+
24
+ (Images use absolute GitHub URLs so they render on npm too; the PNGs ship with the repository, not inside the npm package.)
25
+
26
+ | Deep-read paper note | Video note metadata |
27
+ | --- | --- |
28
+ | ![Paper note](https://raw.githubusercontent.com/PensiveFei/deep-read-summarize/main/docs/showcase/showcase-paper-note-cot.png) | ![Video note metadata](https://raw.githubusercontent.com/PensiveFei/deep-read-summarize/main/docs/showcase/showcase-video-note-metadata.png) |
29
+
30
+ | Video note action items | In-chat digest |
31
+ | --- | --- |
32
+ | ![Video note action items](https://raw.githubusercontent.com/PensiveFei/deep-read-summarize/main/docs/showcase/showcase-video-note-actions.png) | ![In-chat digest](https://raw.githubusercontent.com/PensiveFei/deep-read-summarize/main/docs/showcase/showcase-in-chat-digest.png) |
33
+
34
+ ---
35
+
36
+ ## What it does
37
+
38
+ - Books (PDF/EPUB/MOBI), papers (arXiv/PDF/HTML), videos (**subtitles first, auto-transcription when there are none** — produces a full transcript for deep reading), web pages
39
+ - Long content is chunked and read in parallel by sub-agents, then merged
40
+ - The fetch/chunk plan and the quality check are constrained by JSON Schema, so their output is stable and machine-readable
41
+ - Chunk count — and therefore sub-agent count — is enforced by `maxChunks` (a runaway plan blows the per-call time limit)
42
+ - Key citations must carry page/chapter/paragraph references to reduce fabrication
43
+ - Configuration errors abort immediately; a chunk that fails to parse is skipped and marked as a gap
44
+ - Output drops straight into Obsidian and works with Dataview
45
+
46
+ ---
47
+
48
+ ## Structure
49
+
50
+ ```
51
+ Input (link or file path)
52
+ │
53
+ ▼
54
+ Parser registry ── book / paper / video / web
55
+ │
56
+ ▼
57
+ Wave 1 Fetch content → write temp file → build chunk plan
58
+ │
59
+ ▼
60
+ Wave 2 N sub-agents deep-read chunks in parallel (Map)
61
+ │
62
+ ▼
63
+ Wave 3 Merge draft + quality check (Reduce)
64
+ │
65
+ ▼
66
+ Obsidian note
67
+ ```
68
+
69
+ Three waves, roughly N+2 sub-agents in total, where N is the number of chunks.
70
+
71
+ ```
72
+ parsers/ Parsers for each input type, dispatched by type
73
+ book.js Books: PDF/EPUB/MOBI text extraction, chapter chunking
74
+ paper.js Papers: arXiv/PDF/HTML structure detection
75
+ video.js Video: full transcript (subtitles first; auto-transcribe via scripts/transcribe.js when none)
76
+ web.js Web pages: main-text extraction
77
+ index.js Registry: parser discovery and fallback
78
+ schemas/ JSON Schema for the output contract (injected into the script by workflow.js - single source of truth)
79
+ scripts/ lint, security checks, cross-platform transcription bootstrap (transcribe.js)
80
+ tests/ fixture tests and validation scripts
81
+ workflow.js The workflow script itself (meta + script)
82
+ ```
83
+
84
+ To change how an input type is handled, drop a parser with the same interface into `custom-parsers/`; a type with the same name overrides the built-in implementation, and you can also add a brand-new type name (e.g. `podcast`) - every registered parser is inlined into the workflow script, and both the `type` whitelist and the schema's `kind` enum follow the registry. The interface has only three fields: `name`, `types`, `buildPrompt(input, opts)`.
85
+
86
+ ---
87
+
88
+ ## dsh.so ecosystem
89
+
90
+ This repo carries the `dsh-plugin` topic and the `dsh` field in `package.json`, so it can be indexed by the dsh.so registry.
91
+
92
+ dsh.so listing requirements: a public repo, the `dsh-plugin` topic (or the dsh field), README install instructions, and an SPDX license (MIT).
93
+ 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**.
94
+
95
+ ---
96
+ ## Installation (DSH plugin)
97
+
98
+ deep-read-summarize is a DSH plugin installable via npm, the dsh.so ecosystem, or locally:
99
+
100
+ ```bash
101
+ # npm install (published to the registry, no third-party dependencies)
102
+ npm install deep-read-summarize
103
+
104
+ # or local install (dsh profile directory)
105
+ pnpm add ./deep-read-summarize-0.3.9.tgz
106
+ # then append to the dsh config's dsh.profile.bundles:
107
+ # - deep-read-summarize
108
+ # restart dsh web (POST /dsh-market/restart)
109
+ ```
110
+
111
+ After installation it registers:
112
+ - the `deep-read-summarize` workflow (meta + script)
113
+ - the `deep-read-summarize` skill (`skills/deep-read-summarize/SKILL.md`)
114
+ - four parsers (`parsers/`) and JSON Schemas (`schemas/`)
115
+
116
+ ---
117
+ ## Quick start (~5 minutes)
118
+
119
+ ### 1. Install
120
+
121
+ ```bash
122
+ # Option A: npm install directly (no clone needed)
123
+ npm install deep-read-summarize
124
+
125
+ # Option B: develop from source
126
+ git clone https://github.com/<your-org>/deep-read-summarize.git
127
+ cd deep-read-summarize
128
+ npm install # no third-party dependencies, just initialization
129
+ ```
130
+
131
+ ### 2. Verify the environment (offline, no API key needed)
132
+
133
+ ```bash
134
+ npm test # 25 fixture tests, all run offline
135
+ ```
136
+
137
+ Seeing `TOTAL: 25 passed, 0 failed` means the environment is ready.
138
+
139
+ ### 3. Feed a demo file with one command
140
+
141
+ ```bash
142
+ node -e "const wf = require('./workflow.js'); console.log('meta:', wf.meta.name); console.log('parsers:', wf.parsers.list().map(p => p.name).join(', '));"
143
+ ```
144
+
145
+ Output looks like:
146
+
147
+ ```
148
+ meta: deep-read-summarize
149
+ parsers: book, paper, video, web
150
+ ```
151
+
152
+ ### 4. Real run (requires the DSH workflow tool)
153
+
154
+ Pass the JSON below to DSH's workflow tool (see Usage):
155
+
156
+ ```jsonc
157
+ { "input": "https://arxiv.org/abs/2307.09042", "type": "paper", "options": { "maxChunks": 4, "fastMode": true } }
158
+ ```
159
+
160
+ The workflow returns a structured result: `{ ok, kind, title, filePath, qualityPassed, note }`, where `note` is the final Markdown note.
161
+
162
+ > ⚠️ **The caller persists the note.** DSH's workflow contract gives the script no filesystem access — it only coordinates subagents — so the script returns the note body plus a suggested `filePath` and never writes the file itself. The bundled SKILL.md tells the model to write `note` to `filePath` with the `write` tool after the run; do the same when you invoke the workflow by hand, or the note exists only in the return value.
163
+
164
+ ---
165
+ ## Usage
166
+
167
+ Pass this JSON to DSH's workflow tool:
168
+
169
+ ```jsonc
170
+ {
171
+ "input": "https://arxiv.org/abs/2307.09042", // link or file path
172
+ "type": "auto", // auto | book | paper | video | web
173
+ "options": {
174
+ "minWords": 2500,
175
+ "fastMode": false, // true skips sections 5-7, faster
176
+ "maxChunks": 4, // chunk limit, 1-12 (default lowered to control sub-agent count and time)
177
+ "transcribe": true, // video: auto local transcription (faster-whisper) when no subtitles; false skips it — see Video
178
+ "whisperModel": "small", // video ASR tier: small | base | medium
179
+ "language": "zh", // video ASR language: use "en" for English-only videos
180
+ "device": "cpu", // ASR device: cpu (default) | auto | cuda; auto/cuda needs a CUDA runtime and falls back to cpu
181
+ "requireCitations": true, // whether key conclusions must carry citations
182
+ "includeTimestamps": false,
183
+ "outputDir": "./output", // note output directory (can point at your Obsidian vault)
184
+ "tempDir": "./.tmp" // temp file directory
185
+ }
186
+ }
187
+ ```
188
+
189
+ Examples:
190
+
191
+ | Type | input |
192
+ |------|-------|
193
+ | Paper | `https://arxiv.org/abs/2307.09042` |
194
+ | Book | local path, e.g. `~/books/xxx.pdf` |
195
+ | Video | `https://youtube.com/watch?v=xxx` |
196
+ | Web page | `https://example.com/article` |
197
+
198
+ Notes are written to `options.outputDir` (default `./output`, can point at your Obsidian vault), with the filename taken from the content title.
199
+
200
+ ### Video: full transcript (subtitles first, auto-transcription when none)
201
+
202
+ Video text extraction is a **unified pipeline** (the old "three tiers" are gone): the goal is to get the **full transcript**, then deep-read it.
203
+
204
+ > **⚠️ To preserve deep-reading quality, processing may take noticeably longer (a deliberate trade-off, not a hang)**: a **subtitle-less** video is transcribed first (roughly 0.5–2× the video length on CPU) before deep reading, so such videos are **much slower than subtitled videos**; in exchange you get a **full transcript + real deep reading**. **Subtitled** videos remain seconds-fast. Please do not mistake the slower transcription for a hang.
205
+
206
+ 1. **Platform subtitles available** (Bilibili's official API AI subtitles / YouTube CC) → **use them directly** (= full text, fastest, zero dependencies).
207
+ 2. **No public subtitles** → use the bundled transcription `scripts/transcribe.js` (faster-whisper small / int8 / VAD / Chinese) to get the full text.
208
+ 3. **Neither works** → **degrade gracefully**: prompt the user to supply a transcript manually, or fall back to `desc` as background; **never block**.
209
+
210
+ `options.transcribe`: **default `true`** (auto-transcribe when no subtitles); set `false` to skip transcription (use subtitles/desc or degrade).
211
+
212
+ **Transcription toolchain (identical for you and the author)**: the script **bootstraps itself** — it uses `uv` to create a **Python 3.12** environment + **Tsinghua mirror** to install `faster-whisper`, downloads the model via `HF_ENDPOINT=https://hf-mirror.com` and **caches it for reuse**; faster-whisper bundles PyAV to decode audio, so **no separate ffmpeg** is needed; **versions are pinned** (Python 3.12 / faster-whisper / uv) so the author's environment matches yours. The script is written in **Node**, so **Windows / macOS / Linux share one implementation and one command** (`node scripts/transcribe.js --audio <file> --out <txt>`). Transcription runs on **CPU** by default (`options.device`); GPU needs a CUDA runtime (cuBLAS/cuDNN), so `options.device: "auto"` is opt-in and falls back to CPU automatically. Cache location per platform: Windows `%LOCALAPPDATA%\deep-read-summarize`, macOS `~/Library/Caches/deep-read-summarize`, Linux `$XDG_CACHE_HOME/deep-read-summarize`.
213
+
214
+ > ⚠️ **The first transcription downloads the model first (small ≈ 484 MB, via hf-mirror, not GitHub) and may take a few minutes** — please be patient; **it downloads only once** on your machine, then every later transcription uses the cache and starts instantly. **Only subtitle-less videos trigger transcription** (subtitled videos use their subtitles directly — no trigger, no download).
215
+
216
+ **Quality/speed**: `small` + `int8` quantization + `VAD` silence filtering gives usable Chinese quality and is CPU-friendly. **Subtitled videos are not transcribed (fast)**; subtitle-less videos are transcribed at roughly 0.5–2× the video length on CPU.
217
+
218
+ **Failure handling**: install/download failures **report an error and degrade** (prompt for a manual transcript), never silently and never blocking for long. Use `options.transcribe: false` to skip transcription.
219
+
220
+ **How to know what source was used**: source info is **not written into the note** (to keep it clean); it surfaces in: ① the run log's `[source] <value> -> <label>` line; ② the `textSource` field in the returned result (`subtitle / transcription / desc / manual`).
221
+
222
+ ---
223
+
224
+ ## Variance and influencing factors (why length and content may differ)
225
+
226
+ **Output length and content vary noticeably with the model and the input; this is normal.**
227
+
228
+ ### Model
229
+ - **ASR model tier**: `small` (default, usable for Chinese) → `base` (faster, slightly lower quality) → `medium` (better, slower). Adjust with `options.whisperModel`; download size and speed grow with the model.
230
+ - **Language/accent**: Chinese/English/mixed language, dialect, accent, stress → **different transcription accuracy and time**; for pure English video you can set `language: "en"`.
231
+ - **Deep-reading LLM**: uses the host DSH model; different context/reasoning models → **different quality, length, and speed**.
232
+ - **Non-determinism**: both the LLM and ASR are stochastic, so **re-running the same input may produce slightly different results** (content/length).
233
+
234
+ ### Input
235
+ - **Video**:
236
+ - Whether **public subtitles** exist is the biggest differentiator — public subtitles = seconds-fast; login-only AI subtitles or no subtitles = triggers transcription, **noticeably slower**.
237
+ - **Length**: longer video = longer transcription (≈ 0.5–2× the video length on CPU).
238
+ - **Audio quality/noise/low volume/pure BGM/no voice**: transcription is error-prone or **empty**; supply a transcript manually in that case.
239
+ - **Paper/book/web page**:
240
+ - Format: PDF/EPUB/MOBI/HTML/arXiv; **scanned OCR, broken PDFs, dense formulas/figures** → different extraction quality and time.
241
+ - **Term density/length** → different chunk count and deep-reading depth.
242
+ - **Chunking structure**: different types chunk differently (chapter/topic/paragraph), affecting **output structure** and coverage.
243
+
244
+ ### Hardware
245
+ - **GPU vs CPU**: GPU transcription can be an order of magnitude faster than CPU (`device='auto'` picks automatically). Subtitle-less videos are ≈ 0.5–2× the length on CPU.
246
+
247
+ ### Other
248
+ - **First run vs reuse**: the first run downloads the model (≈ 484 MB); later runs reuse the cache.
249
+ - **Token/cost**: chunk count, length, and citations drive token usage; `fastMode`/`maxChunks` save tokens.
250
+ - **Citation/fabrication**: transcription or OCR errors may be quoted as "original text"; **re-check key citations**.
251
+ - **Boundaries**: pure BGM, distorted audio → empty/poor transcription; no subtitles and transcription unavailable → degrade to a prompt for a manual transcript.
252
+
253
+ ---
254
+
255
+ ## How failures are handled
256
+
257
+ Two classes:
258
+
259
+ - **Configuration errors** (missing input, invalid type, malformed options): throw immediately and abort — no half-baked output.
260
+ - **Content problems** (fetch failed, a chunk's deep-read failed): return `{ ok: false, stage, fatal: false }` and let the caller decide. A failed chunk is skipped and marked as a gap in the draft; the whole run is not aborted.
261
+
262
+ ---
263
+
264
+ ## Cost
265
+
266
+ A paper, 6 chunks, full mode: roughly 15–25k tokens. `fastMode` with a lower `maxChunks` saves about 40%.
267
+
268
+ ---
269
+
270
+ ## Security & copyright
271
+
272
+ - Fetching videos/web pages makes external requests, executed by sub-agents under DSH's sandbox and approval policy; don't let a model run arbitrary scripts unattended.
273
+ - Sub-agents need appropriate permissions to write files; if permissions are insufficient, the workflow returns the content and the main agent handles persistence.
274
+ - **Local transcription**: video transcription (faster-whisper) runs **locally**; audio/subtitles **do not leave your machine**; network requests to the corresponding platforms are made only when fetching video metadata/subtitles/audio.
275
+ - This repo contains only the pipeline itself: workflow definitions, parser code, prompt templates, schemas. **It contains no extracted copyrighted content.** Test fixtures are self-written public-domain fables. When you process copyrighted material with this workflow, responsibility for the output is yours.
276
+
277
+ ---
278
+
279
+ ## Development
280
+
281
+ ```bash
282
+ npm install
283
+ npm run lint # node --check on all JS
284
+ npm test # fixture tests (25, all offline)
285
+ npm run validate # pre-release validation (including security checks)
286
+ ```
287
+
288
+ `npm publish` automatically runs `prepublishOnly` (tests + lint + security checks) first; any failure blocks the publish.
289
+
290
+ See CHANGELOG.md for changes and CONTRIBUTING.md for contribution guidelines.
291
+
292
+ ---
293
+
294
+ ## Compatibility
295
+
296
+ **Verified host: DSH 0.1.2-rc.1** (Node 24). The dependency surface is exactly two things:
297
+
298
+ | Surface | Current contract | How this repo uses it |
299
+ | --- | --- | --- |
300
+ | workflow script hooks | `agent()` / `pipeline()` / `parallel()` / `phase()` / `log()` / `args` | only `agent/parallel/phase/log/args`; `agent()` options limited to `label/phase/schema` (the engine accepts only `label/phase/schema/provider/model` and treats anything else as fatal) |
301
+ | JSON Schema subset | `type / properties / required / additionalProperties / items / enum / const / oneOf` plus annotation keys | both `agent()` schemas verified against the host's real `assertObjectJsonSchema` |
302
+
303
+ Two contract details that bite:
304
+
305
+ - **The script sandbox has no filesystem, network, timers or `require`** — it coordinates subagents; the caller persists the note (see ⚠️ above).
306
+ - **Breaking the schema subset terminates the run** rather than degrading: the engine raises `UNSUPPORTED_SCHEMA` and the whole workflow fails. `npm test` carries a regression for this, including a reverse assertion so the checker cannot pass vacuously.
307
+
308
+ After upgrading DSH, run `npm test` and `npm run test:node`; if something breaks, cross-reference CHANGELOG.md.
309
+
310
+ ---
311
+
312
+ ## License
313
+
314
+ MIT — see [LICENSE](LICENSE).
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  [![MIT license](https://img.shields.io/github/license/PensiveFei/deep-read-summarize)](https://github.com/PensiveFei/deep-read-summarize/blob/main/LICENSE)
4
4
  [![release](https://img.shields.io/github/v/release/PensiveFei/deep-read-summarize)](https://github.com/PensiveFei/deep-read-summarize/releases)
5
5
  [![CI](https://img.shields.io/github/actions/workflow/status/PensiveFei/deep-read-summarize/ci.yml)](https://github.com/PensiveFei/deep-read-summarize/actions/workflows/ci.yml)
6
- [![npm downloads](https://img.shields.io/npm/dw/deep-read-summarize)](https://www.npmjs.com/package/deep-read-summarize)
6
+ [![npm downloads](https://badgen.net/npm/dm/deep-read-summarize)](https://www.npmjs.com/package/deep-read-summarize)
7
7
 
8
8
  > **Disclaimer**: This is an **unofficial third-party tool**. It is not affiliated with, endorsed by, or sponsored by DeepSeek or the DeepSeek Harness project. "DeepSeek" and "DeepSeek Harness" are trademarks of their respective owners. This project only orchestrates the workflow tool available in your DSH environment; it does not redistribute any DeepSeek software.
9
9
 
@@ -19,11 +19,26 @@
19
19
 
20
20
  ---
21
21
 
22
+ ## 实际效果
23
+
24
+ (图用 GitHub 绝对地址,npm 页面同样能显示;图片本身不打进 npm 包,只随仓库分发)
25
+
26
+ | 精读论文 | 视频笔记(元信息) |
27
+ | --- | --- |
28
+ | ![论文精读笔记](https://raw.githubusercontent.com/PensiveFei/deep-read-summarize/main/docs/showcase/showcase-paper-note-cot.png) | ![视频笔记元信息](https://raw.githubusercontent.com/PensiveFei/deep-read-summarize/main/docs/showcase/showcase-video-note-metadata.png) |
29
+
30
+ | 视频笔记(行动要点) | 会话内摘要 |
31
+ | --- | --- |
32
+ | ![视频笔记行动要点](https://raw.githubusercontent.com/PensiveFei/deep-read-summarize/main/docs/showcase/showcase-video-note-actions.png) | ![会话内摘要](https://raw.githubusercontent.com/PensiveFei/deep-read-summarize/main/docs/showcase/showcase-in-chat-digest.png) |
33
+
34
+ ---
35
+
22
36
  ## 能做什么
23
37
 
24
38
  - 书籍(PDF/EPUB/MOBI)、论文(arXiv/PDF/HTML)、视频(**字幕优先,无字幕自动转写**,出品完整逐字稿精读)、网页
25
39
  - 长内容分块后由并行子代理精读,再合并
26
- - 各子任务的输出用 JSON Schema 约束,不合格自动重试
40
+ - 获取/分块与质量校验的输出受 JSON Schema 约束,结构稳定、下游可解析
41
+ - 分块计划与子代理数量受 `maxChunks` 强制约束(计划失控会顶穿单次调用时限)
27
42
  - 关键引用必须标注页码/章节/段落,降低编造风险
28
43
  - 配置错误直接报错终止;某块内容解析失败则跳过并标记缺口
29
44
  - 输出可直接放进 Obsidian,配合 Dataview 使用
@@ -57,16 +72,16 @@ Obsidian 笔记
57
72
  parsers/ 各输入类型的解析器,按类型分发
58
73
  book.js 书籍:PDF/EPUB/MOBI 文本提取、章节分块
59
74
  paper.js 论文:arXiv/PDF/HTML 结构识别
60
- video.js 视频:完整逐字稿(字幕优先,无字幕自动转写,走 scripts/transcribe.ps1)
75
+ video.js 视频:完整逐字稿(字幕优先,无字幕自动转写,走 scripts/transcribe.js)
61
76
  web.js 网页:正文提取
62
77
  index.js 注册表:解析器发现与回退
63
- schemas/ 子任务输出的 JSON Schema
64
- scripts/ lint、安全检查
78
+ schemas/ 输出约束的 JSON Schema(波次1 由 workflow.js 注入脚本,单一真相)
79
+ scripts/ lint、安全检查、跨平台转写引导(transcribe.js)
65
80
  tests/ fixture 测试与验证脚本
66
81
  workflow.js workflow 脚本本体(meta + script)
67
82
  ```
68
83
 
69
- 想换某个输入类型的处理方式,在 `custom-parsers/` 放一个同接口的解析器即可,同名类型会覆盖内置实现。接口只有三个字段:`name`、`types`、`buildPrompt(input, opts)`。
84
+ 想换某个输入类型的处理方式,在 `custom-parsers/` 放一个同接口的解析器即可,同名类型会覆盖内置实现;用新类型名(如 `podcast`)也可以——注册表里的解析器会全部内联进 workflow 脚本,`type` 白名单与 schema 的 `kind` 枚举都跟着注册表走。接口只有三个字段:`name`、`types`、`buildPrompt(input, opts)`。
70
85
 
71
86
  ---
72
87
 
@@ -87,7 +102,7 @@ deep-read-summarize 是 DSH 插件,可通过 npm、dsh.so 生态或本地安
87
102
  npm install deep-read-summarize
88
103
 
89
104
  # 或本地安装(dsh profile 目录)
90
- pnpm add ./deep-read-summarize-0.3.6.tgz
105
+ pnpm add ./deep-read-summarize-0.3.9.tgz
91
106
  # 然后在 dsh 配置的 dsh.profile.bundles 追加:
92
107
  # - deep-read-summarize
93
108
  # 重启 dsh web 即可(POST /dsh-market/restart)
@@ -144,6 +159,8 @@ parsers: book, paper, video, web
144
159
 
145
160
  工作流会返回结构化结果:`{ ok, kind, title, filePath, qualityPassed, note }`,`note` 即最终 Markdown 笔记。
146
161
 
162
+ > ⚠️ **笔记由主代理落盘**:DSH 的 workflow 契约规定脚本只能协调子代理(沙箱内没有文件系统),所以脚本只返回 `note` 正文与建议路径 `filePath`,**不会自己写文件**。插件自带的 SKILL.md 已明确要求模型在拿到结果后用 `write` 工具写入 `filePath`——自己拼 workflow 调用时也要记得这一步,否则笔记只存在于返回值里。
163
+
147
164
  ---
148
165
  ## 用法
149
166
 
@@ -158,6 +175,9 @@ parsers: book, paper, video, web
158
175
  "fastMode": false, // true 时跳过 5-7 节,速度快一些
159
176
  "maxChunks": 4, // 分块上限,1-12(默认调低,控制子代理数与耗时)
160
177
  "transcribe": true, // 视频:无字幕时自动本地转写(faster-whisper);false 则跳过转写,见「视频」节
178
+ "whisperModel": "small", // 视频转写模型档位:small | base | medium
179
+ "language": "zh", // 视频转写语言:纯英文视频可设 "en"
180
+ "device": "cpu", // 转写设备:cpu(默认)| auto | cuda;auto/cuda 需自备 CUDA 运行库,失败自动回退 cpu
161
181
  "requireCitations": true, // 关键结论是否必须标注出处
162
182
  "includeTimestamps": false,
163
183
  "outputDir": "./output", // 笔记输出目录(可指向 Obsidian 仓库)
@@ -184,12 +204,12 @@ parsers: book, paper, video, web
184
204
  > **⚠️ 为保证精读质量,处理时间可能略长(刻意取舍,不是卡死)**:**无字幕**视频会先做一次转写(CPU 上约为视频时长的 0.5–2×)再精读,所以这类视频整体会**明显比有字幕视频慢**;换来的是**完整逐字稿 + 真正的精读**。**有字幕**视频仍是秒级。请勿把转写的较慢误判为卡死。
185
205
 
186
206
  1. **有平台字幕**(B站官方 API 的 AI 字幕 / YouTube CC)→ **直接用字幕**(=全文,最快、零依赖)。
187
- 2. **无公开字幕** → 用插件自带转写 `scripts/transcribe.ps1`(faster-whisper small / int8 / VAD / 中文)得到全文。
207
+ 2. **无公开字幕** → 用插件自带转写 `scripts/transcribe.js`(faster-whisper small / int8 / VAD / 中文)得到全文。
188
208
  3. 都不行 → **降级**:提示手动提供转写文本,或退回 `desc` 作背景;**绝不阻塞**。
189
209
 
190
210
  `options.transcribe`:**默认 `true`**(无字幕自动转写);设为 `false` 则跳过转写(只用字幕/desc 或降级)。
191
211
 
192
- **转写工具链(本机/用户一致)**:脚本**自举**——用 `uv` 建 **Python 3.12** 环境 + **清华镜像**装 `faster-whisper` + `HF_ENDPOINT=https://hf-mirror.com` 下模型并**缓存复用**;faster-whisper 内置 PyAV 解码音频,**无需单独 ffmpeg**;**版本已锁定**(Python 3.12 / faster-whisper / uv),保证本机与用户环境一致。
212
+ **转写工具链(本机/用户一致)**:脚本**自举**——用 `uv` 建 **Python 3.12** 环境 + **清华镜像**装 `faster-whisper` + `HF_ENDPOINT=https://hf-mirror.com` 下模型并**缓存复用**;faster-whisper 内置 PyAV 解码音频,**无需单独 ffmpeg**;**版本已锁定**(Python 3.12 / faster-whisper / uv),保证本机与用户环境一致。脚本是 **Node** 写的,**Windows / macOS / Linux 同一份实现、同一条命令**(`node scripts/transcribe.js --audio <音频> --out <txt>`);转写默认走 **CPU**(`options.device` 默认 `cpu`),GPU 需自备 CUDA 运行库(cuBLAS/cuDNN),可设 `options.device: "auto"` 尝试,失败会自动回退 CPU。缓存目录按平台取:Windows `%LOCALAPPDATA%\deep-read-summarize`、macOS `~/Library/Caches/deep-read-summarize`、Linux `$XDG_CACHE_HOME/deep-read-summarize`。
193
213
 
194
214
  > ⚠️ **首次转写会先下载模型(small 约 484MB,走 hf-mirror,非 GitHub),可能需要几分钟**,请耐心等待;**本机只下这一次**,之后所有视频转写用缓存、秒开。**只有「无字幕」视频才会触发转写**(有字幕的视频直接用字幕,不触发、不下载)。
195
215
 
@@ -273,15 +293,22 @@ npm publish 会自动先跑 prepublishOnly(测试 + lint + 安全检查),
273
293
 
274
294
  ## 兼容性
275
295
 
276
- DSH 还在快速迭代,有过破坏性变更。本仓库的依赖面是:
296
+ **已验证的宿主:DSH 0.1.2-rc.1**(Node 24)。本仓库的依赖面只有两处:
297
+
298
+ | 依赖面 | 现行契约 | 本仓库的用法 |
299
+ | --- | --- | --- |
300
+ | workflow 脚本钩子 | `agent()` / `pipeline()` / `parallel()` / `phase()` / `log()` / `args` | 只用了 `agent/parallel/phase/log/args`;`agent()` 选项只用 `label/phase/schema`(引擎只接受 `label/phase/schema/provider/model`,其它选项会被判为 fatal) |
301
+ | JSON Schema 子集 | `type / properties / required / additionalProperties / items / enum / const / oneOf` + 注解键 | 两个 `agent()` schema 已用宿主真实的 `assertObjectJsonSchema` 实测通过 |
302
+
303
+ 两点容易踩的契约细节:
277
304
 
278
- - workflow 工具的 `agent()`、`parallel()`、`phase()`、`log()`、`args`
279
- - JSON Schema 子集:`type / properties / required / additionalProperties / items / enum / const / oneOf`
305
+ - **脚本沙箱没有文件系统/网络/定时器/require**——只能协调子代理;笔记落盘由主代理完成(见上文 ⚠️)。
306
+ - **违反上述子集不是降级而是终止**:引擎抛 `UNSUPPORTED_SCHEMA`,整条 workflow 直接失败。仓库的 `npm test` 里有对应回归(含反向断言,确保校验器不是空放行)。
280
307
 
281
- 升级 DSH 后先跑一遍 `npm test`。如果坏了,对照 CHANGELOG.md 里的版本记录排查。
308
+ 升级 DSH 后先跑 `npm test` + `npm run test:node`;坏了对照 CHANGELOG.md 排查。
282
309
 
283
310
  ---
284
311
 
285
312
  ## License
286
313
 
287
- MIT,见 [LICENSE](LICENSE)。
314
+ MIT,见 [LICENSE](LICENSE)。
package/cordis.patch.yml CHANGED
@@ -10,13 +10,20 @@
10
10
  - id: deep-read-summarize
11
11
  name: 'deep-read-summarize'
12
12
 
13
- # All plugin config keys are optional; defaults are applied by the plugin.
13
+ # All plugin config keys are optional. The plugin validates each one (wrong type
14
+ # = warning + ignore, never a startup failure) and folds them into the default
15
+ # args carried by the skill, so they become this profile's defaults.
14
16
  # config:
15
17
  # outputDir: './output' # where notes are written (default: ./output)
16
18
  # tempDir: './.tmp' # temp files for chunked content (default: ./.tmp)
17
- # minWords: 2500 # minimum output length
18
- # fastMode: false # skip sections 5-7 for speed
19
- # maxChunks: 6 # chunk cap (1-12)
20
- # requireCitations: true # key conclusions must cite source location
21
- # includeTimestamps: false # video timestamps (off by default)
22
- # cache: true # idempotency cache on input fingerprint
19
+ # minWords: 2500 # minimum output length (default: 2500)
20
+ # fastMode: false # skip sections 5-7 for speed (default: false)
21
+ # maxChunks: 4 # chunk cap; also caps sub-agent count (1-12, default: 4)
22
+ # transcribe: true # video: auto-transcribe when no subtitles (default: true)
23
+ # requireCitations: true # key conclusions must cite source location (default: true)
24
+ # includeTimestamps: false # video timestamps (default: false)
25
+ #
26
+ # Idempotency is deliberately NOT a plugin config key: the workflow script runs
27
+ # without a filesystem, so it cannot write a fingerprint record. Programmatic
28
+ # callers can use `deep-read-summarize/lib/cache`
29
+ # (fingerprint / hasProcessed / markProcessed).