deep-read-summarize 0.6.1 → 0.6.3

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
@@ -5,6 +5,62 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ### Changed
9
+
10
+ - **补齐中文描述与关键词**:`package.json` 的 `description` 改为中英对照,并显式包含「精读 / 读书笔记 / 论文精读 / 视频总结」这四个**完整短语**;`keywords` 追加同样四个中文词;GitHub 仓库描述同步。
11
+ - 用「视频**总结**」而不是「视频转写」:转写是内部实现,用户会搜的是「视频总结」。
12
+ - 为什么必须是完整短语而不是单个词:DSH 市场的搜索规则是「查询里的每个词都必须作为**子串**出现在**同一个字段**内」,而中文不会被空格切分——只写「论文」「视频」,中文用户搜「论文精读」「视频总结」时一个都命中不了。
13
+ - 之所以动描述而不是只堆 keywords:市场只索引 `name` / `npm` 名 / `owner` / 描述 / 分类,**完全不读 keywords**;npm 搜索的默认排序又由热度主导,keywords 的边际作用接近零。
14
+
15
+ ## [0.6.3] — 2026-11-12
16
+
17
+ 修复获取阶段把「子代理没有返回结构化结果」误报成内容获取失败的问题,并让获取提示词的 JSON 示例合法、可被结构化输出接受。
18
+
19
+ ### Fixed
20
+
21
+ - **两种获取失败被合并成一句话**:子代理失败时 `agent()` 兑现 `null`(没调用 `structured_output`,或运行失败),这与子代理明确返回 `{ "saved": false }` 不是同一件事——内容可能已经写入目标文件。此前两者共用「获取失败(可降级:检查输入或手动提供文本)」,把结果通道的问题说成来源问题,让用户回头重查一个本来没问题的链接。现在前者单独报告「未收到可用的获取结果」,后者保留子代理自报的 `message`,抛错路径不变。
22
+ - **获取提示词的示例不合法**:四个内置解析器的 JSON 示例里 `"totalLines": N` 不是合法 JSON,`"language": "zh|en"` 超出 `fetchResultSchema` 的枚举,视频解析器的 `"textSource"` 同样是「多选一」的写法。模型照抄示例时,`structured_output` 会以参数校验失败拒绝——正好落进上面那条死路。示例改为合法取值,并在提示词里写明这些字段必须填本次实际值(照抄示例行数会截断原文)。
23
+ - **提示词与宿主的结构化输出要求相抵**:获取与类型识别提示词都以「只输出 JSON」结尾,等于教子代理把 JSON 写在正文里;宿主的要求是必须以 `structured_output` 工具调用结束。改为按结构化输出通道提交。
24
+
25
+ ### Verification
26
+
27
+ - 用确定性子代理重放获取阶段的四种返回值:`null`、`{ "saved": false }`、带 `message` 的 `{ "saved": false }` 以及抛错,确认前两条的消息不再相同、`message` 原样保留、抛错路径不变(`tests/workflow-regressions.test.js`)。
28
+ - 新增示例校验测试:四个内置解析器的示例必须能被 `JSON.parse`,且 `language` 落在 schema 枚举内、`totalLines` 为数字、视频 `textSource` 在文档允许的取值内(`tests/parser-entry-audit.test.js`)。
29
+ - 本地 Node 24 上 `npm test`、`npm run test:node`、`npm run lint`、`npm run security`、`npm run validate` 全绿;本次未做真实模型端到端调用。
30
+
31
+ ### Compatibility
32
+
33
+ - 升级无需更改配置;返回结构(`ok` / `stage` / `fatal`)不变,变化只在失败消息文案与提示词。已有缓存与已保存的成稿不受影响。
34
+
35
+ ### 已知问题
36
+
37
+ - 宿主把「子代理没调用 `structured_output`」和「子代理运行失败」都兑现成 `null`,插件无法区分,只能如实报告「未收到可用的获取结果」,不再猜测属于哪一种。
38
+
39
+ ### 贡献者与致谢
40
+
41
+ - 感谢 @qneko 报告并复现获取阶段错误信息合并、提示词示例不合法的问题,并附上受控重放结果([Issue #10](https://github.com/PensiveFei/deep-read-summarize/issues/10))。
42
+
43
+ ## [0.6.2] — 2026-11-11
44
+
45
+ 修复成稿包含前言或外层 Markdown 围栏时,笔记被误判为格式、篇幅和引用不合格的问题。
46
+
47
+ ### Fixed
48
+
49
+ - **成稿包装导致质量误报**:识别唯一、明确的完整 Markdown 笔记,先移除其外层围栏或前言,再对同一份正文执行格式、篇幅和独立原文核验并返回;普通代码块仍不计入正文。无法明确提取时保留原始回复并照常报告质量问题。
50
+ - 可选的 `draftContext` 记录提取方式以及模型在笔记前后附带的说明;主代理向用户说明这些额外文字,它们没有通过笔记的原文核验。
51
+
52
+ ### Verification
53
+
54
+ - 回归测试覆盖普通成稿、围栏包装、修订稿、嵌套代码块及提取有歧义的情况。使用 DSH 真实模型精读论文,并在成稿后人为添加围栏,确认格式和篇幅检查不再受外层包装影响;该次笔记的引用核验未通过,真实质量问题仍会照常报告。
55
+
56
+ ### Compatibility
57
+
58
+ - 升级无需更改配置;只有识别到可明确提取的笔记时才移除包装,额外文字通过可选的 `draftContext` 返回。
59
+
60
+ ### 贡献者与致谢
61
+
62
+ - 感谢 @qneko 报告和复现成稿外层 Markdown 围栏造成的质量误报([Issue #9](https://github.com/PensiveFei/deep-read-summarize/issues/9))。
63
+
8
64
  ## [0.6.1] — 2026-11-10
9
65
 
10
66
  修复普通执行路径的结果序列化错误,避免已生成的精读笔记在返回宿主时被丢弃。
package/README.en.md CHANGED
@@ -65,6 +65,8 @@ You can also provide a local file, web page, or video link. If needed, specify a
65
65
 
66
66
  Hosts with plugin-tool support register `deep_read_summarize`; older hosts use the bundled skill and workflow entry point. The tool returns the note and a suggested path; **the main agent must write the file**. Check that the file was saved and whether the result reports gaps or quality issues.
67
67
 
68
+ When an identifiable note is extracted from a wrapper, the optional `draftContext` field records the extraction and retains any surrounding text. That text is not part of the note reviewed against the source.
69
+
68
70
  <details>
69
71
  <summary>Direct tool-call example</summary>
70
72
 
package/README.md CHANGED
@@ -65,6 +65,8 @@ https://arxiv.org/abs/2307.09042
65
65
 
66
66
  支持插件工具的宿主会注册 `deep_read_summarize`;旧宿主使用插件提供的技能和 workflow 入口。精读工具返回笔记正文及建议路径,**实际写入文件需要由主代理完成**。生成后请确认文件已保存,并检查结果中是否报告内容缺口或质量问题。
67
67
 
68
+ 当工作流提取被包装的笔记时,可选字段 `draftContext` 会记录提取方式,以及模型在笔记前后附带的额外说明。这些额外文字不是经过原文核验的笔记正文。
69
+
68
70
  <details>
69
71
  <summary>直接调用工具的参数示例</summary>
70
72
 
package/docs/RELEASE.md CHANGED
@@ -156,7 +156,9 @@ npm view deep-read-summarize --prefer-online # 验证线
156
156
  | v0.4.0 | npm 已发布 | 保留完整精读与独立原文核验,减少脚本搬运、并发空等和无效修订,并修复来源质量判断与视频分P等问题。 |
157
157
  | v0.5.0 | npm 已发布 | 无字幕视频新增逐字稿内容缓存、转写阶段计时和 CPU 线程配置,保留默认精读与原文核验门槛。 |
158
158
  | v0.6.0 | npm 已发布 | 新增可配置并发、字符均衡分块与可选的并行原文核验和跨次精读缓存,保留原有默认核验路径。 |
159
- | **v0.6.1** | **npm 已发布(当前)** | 修复普通执行路径的结果序列化错误,避免已生成的精读笔记在返回宿主时被丢弃。 |
159
+ | v0.6.1 | npm 已发布 | 修复普通执行路径的结果序列化错误,避免已生成的精读笔记在返回宿主时被丢弃。 |
160
+ | v0.6.2 | npm 已发布 | 修复成稿包含前言或外层 Markdown 围栏时,笔记被误判为格式、篇幅和引用不合格的问题。 |
161
+ | **v0.6.3** | **npm 已发布(当前)** | 修复获取阶段把「子代理没有返回结构化结果」误报成内容获取失败的问题,并让获取提示词的 JSON 示例合法、可被结构化输出接受。 |
160
162
  | v1.0.0 | 计划 | API 稳定后发布 |
161
163
 
162
164
  > 早期迭代用 0.x 表达不稳定;API 稳定后再发 1.0.0。
package/lib/quality.js CHANGED
@@ -1,7 +1,58 @@
1
1
  'use strict';
2
2
 
3
- // Both functions are self-contained so workflow.js can inline them into the
3
+ // These functions are self-contained so workflow.js can inline them into the
4
4
  // coordination sandbox. They never evaluate YAML or read files themselves.
5
+ function extractNote(reply) {
6
+ const unchanged = { note: reply, context: null };
7
+ if (typeof reply !== 'string' || /^\s*---[ \t]*\r?\n/.test(reply)) return unchanged;
8
+ const lines = reply.split('\n');
9
+ function line(index) { return lines[index].replace(/\r$/, ''); }
10
+ function slice(start, end) { return lines.slice(start, end).join('\n').replace(/\r$/, ''); }
11
+ function outsideIsProse(value) {
12
+ return value.length <= 512 && !/^(?: {0,3}(?:#{1,6}[ \t]|>|[-+*][ \t]|\d+[.)][ \t]|\||[\x60~]{3,})|[ \t]*---[ \t]*$)/m.test(value);
13
+ }
14
+ function looksLikeNote(value) {
15
+ const front = value.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/);
16
+ return !!front && /^title:[ \t]*\S/m.test(front[1]) && /^#[ \t]+\S/m.test(value.slice(front[0].length));
17
+ }
18
+ function extracted(note, kind, before, after) {
19
+ const prefix = before.trim(), suffix = after.trim();
20
+ return { note, context: { kind, before: prefix, after: suffix } };
21
+ }
22
+
23
+ // A short plain-text preamble can precede an otherwise ordinary note,
24
+ // including one with its own code examples. Preserve that preamble.
25
+ for (let i = 1; i < lines.length; i++) {
26
+ if (!/^---[ \t]*$/.test(line(i))) continue;
27
+ const prefix = slice(0, i);
28
+ if (!outsideIsProse(prefix)) break;
29
+ const candidate = lines.slice(i).join('\n');
30
+ if (looksLikeNote(candidate)) return extracted(candidate, 'preamble', prefix, '');
31
+ }
32
+
33
+ // Treat only a single, closed top-level Markdown fence as an outer wrapper.
34
+ // Longer or differently marked inner fences remain part of the note.
35
+ const blocks = [];
36
+ for (let i = 0; i < lines.length; i++) {
37
+ const open = line(i).match(/^ {0,3}([\x60]{3,}|~{3,})(.*)$/);
38
+ if (!open) continue;
39
+ let end = i + 1;
40
+ for (; end < lines.length; end++) {
41
+ const close = line(end).match(/^ {0,3}([\x60]+|~+)[ \t]*$/);
42
+ if (close && close[1][0] === open[1][0] && close[1].length >= open[1].length) break;
43
+ }
44
+ if (end === lines.length) return unchanged;
45
+ blocks.push({ start: i, end, info: open[2].trim() });
46
+ i = end;
47
+ }
48
+ if (blocks.length !== 1 || !/^(?:markdown|md)?$/i.test(blocks[0].info)) return unchanged;
49
+ const block = blocks[0], before = slice(0, block.start), after = slice(block.end + 1);
50
+ const candidate = slice(block.start + 1, block.end)
51
+ .replace(/^(?:[ \t]*\r?\n)+/, '').replace(/(?:\r?\n[ \t]*)+$/, '');
52
+ if (!outsideIsProse(before) || !outsideIsProse(after) || !looksLikeNote(candidate)) return unchanged;
53
+ return extracted(candidate, 'fenced', before, after);
54
+ }
55
+
5
56
  function checkNoteStructure(note, options) {
6
57
  const opts = options || {};
7
58
  const issues = [];
@@ -215,4 +266,4 @@ function validateSourceCheck(check, context) {
215
266
  return { passed: issues.length === 0 && gates.every(gate => results[gate]), checks: results, issues, chunkChecks, citationChecks };
216
267
  }
217
268
 
218
- module.exports = { checkNoteStructure, validateSourceCheck };
269
+ module.exports = { extractNote, checkNoteStructure, validateSourceCheck };
@@ -99,7 +99,7 @@ if (!cacheResume && forcedType === "auto") {
99
99
  required: ["kind"], additionalProperties: false
100
100
  };
101
101
  const detectPrompt = [
102
- "识别输入内容类型,选择后续获取全文所需的解析器,只输出 JSON {\"kind\": \"类型\"}。",
102
+ "识别输入内容类型,选择后续获取全文所需的解析器,按 {\"kind\": \"类型\"} 提交结构化结果(不要把 JSON 只写在正文里)。",
103
103
  "可用类型:" + parserNames.join(", ") + "。book=书籍,paper=学术论文,video=视频,web=网页/文章。",
104
104
  "PDF 既可能是书籍也可能是论文;未知网站可能承载论文或在线书籍,不要仅凭扩展名或网页形式判断。",
105
105
  "必要时只查看标题、摘要、目录或页面元信息,不获取或精读全文,不写入文件。",
@@ -145,9 +145,16 @@ catch (error) {
145
145
  }
146
146
 
147
147
  // 失败纪律:内容获取失败 = 可降级错误(返回失败结果,不抛 fatal)
148
- if (!fetched || !fetched.saved) {
148
+ // agent() 以 null 兑现子代理失败,这与「子代理明确报告 saved:false」不是一回事:
149
+ // null 只说明没拿到结构化结果(可能没调用 structured_output,或子代理运行失败),
150
+ // 不能据此断言内容没取到——把两者并成一句话会把排查引向错误的方向。
151
+ if (!fetched || typeof fetched !== "object") {
149
152
  timings.fetch = Date.now() - fetchStartedAt;
150
- return timedResult({ ok: false, stage: "fetch", fatal: false, message: (fetched && fetched.message) || "获取失败(可降级:检查输入或手动提供文本)" });
153
+ return timedResult({ ok: false, stage: "fetch", fatal: false, message: "未收到可用的获取结果:子代理没有返回结构化结果(可能未调用 structured_output,或子代理运行失败);可重试,或手动提供正文文本后重跑" });
154
+ }
155
+ if (!fetched.saved) {
156
+ timings.fetch = Date.now() - fetchStartedAt;
157
+ return timedResult({ ok: false, stage: "fetch", fatal: false, message: fetched.message || "获取失败(可降级:检查输入或手动提供文本)" });
151
158
  }
152
159
  // 先校验完整计划,按行排序、裁掉重复覆盖并补齐缺口,再合并相邻块。
153
160
  // 块数上限约束的是子代理数量,不能通过丢掉尾部原文来实现。
@@ -376,7 +383,7 @@ if (fmProfile === "obsidian") {
376
383
  fm.push("---");
377
384
 
378
385
  const draftPrompt = [
379
- "将以下多块精读结果整合为完整的结构化精读笔记,只输出标准 Markdown(含 YAML frontmatter)。",
386
+ "将以下多块精读结果整合为完整的结构化精读笔记,只输出标准 Markdown(含 YAML frontmatter),不要前言、结尾说明或包裹整篇笔记的代码围栏;笔记内部需要的代码块可保留。",
380
387
  sourceComplete ? "来源完整性仍需由独立原文核验确认。" : "本次来源不完整。必须在正文开头保留以下可见来源限制,不得称为完整视频精读或补写未取得的视频内容:\n" + sourceNotice,
381
388
  "模板:"
382
389
  ].concat(fm, [
@@ -410,7 +417,10 @@ if (typeof draft !== "string" || !draft.trim()) return timedResult({ ok: false,
410
417
  // ---------- 5. 程序检查 + 独立原文核验 ----------
411
418
  phase("质量校验");
412
419
  const qualityStartedAt = Date.now();
413
- let verified = draft;
420
+ const extractedDraft = __quality.extractNote(draft);
421
+ let verified = extractedDraft.note;
422
+ const draftContext = [];
423
+ if (extractedDraft.context) draftContext.push(Object.assign({ stage: "draft" }, extractedDraft.context));
414
424
  let passed = false;
415
425
  let issues = [];
416
426
  let qualityChecks = {};
@@ -560,7 +570,7 @@ for (let round = 0; round <= maxRetries; round++) {
560
570
  if (!repairableSource) break;
561
571
  if (round < maxRetries) {
562
572
  const fixPrompt = [
563
- "修正以下笔记以解决校验问题,输出完整修正版:",
573
+ "修正以下笔记以解决校验问题,只输出完整修正版 Markdown,不要前言、结尾说明或包裹整篇笔记的代码围栏:",
564
574
  issues.map(function (s) { return "- " + s; }).join("\n"),
565
575
  "原文路径和覆盖证据(必要时用 read 核对,不能臆造缺口):", JSON.stringify(sourceContext),
566
576
  "必须保留的 frontmatter 模板:", fm.join("\n"),
@@ -575,11 +585,13 @@ for (let round = 0; round <= maxRetries; round++) {
575
585
  if (typeof repaired !== "string" || !repaired.trim()) {
576
586
  issues.push("修正结果为空或不是字符串,已保留上一份有效笔记"); break;
577
587
  }
578
- const repairedStructure = __quality.checkNoteStructure(repaired, structureOptions);
588
+ const extractedRepair = __quality.extractNote(repaired);
589
+ const repairedStructure = __quality.checkNoteStructure(extractedRepair.note, structureOptions);
579
590
  if (!repairedStructure.formatComplete || (localCheck.lengthMet && !repairedStructure.lengthMet)) {
580
591
  issues.push("修正结果格式不完整或篇幅退化,已保留上一份有效笔记"); break;
581
592
  }
582
- verified = repaired;
593
+ verified = extractedRepair.note;
594
+ if (extractedRepair.context) draftContext.push(Object.assign({ stage: "repair" }, extractedRepair.context));
583
595
  }
584
596
  }
585
597
 
@@ -603,6 +615,7 @@ return timedResult({
603
615
  coverageComplete: coverageComplete,
604
616
  textSource: textSource,
605
617
  sourceComplete: sourceComplete,
618
+ ...(draftContext.length ? { draftContext: draftContext } : {}),
606
619
  note: verified,
607
620
  ...(cacheResume ? { __cacheReads: reads } : {})
608
621
  });
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "deep-read-summarize",
3
- "version": "0.6.1",
4
- "description": "Deep reading & summarization for DSH: books/papers/videos/web → structured Markdown notes with YAML frontmatter. Plugin parsers, MapReduce deep-read, JSON Schema-constrained sub-tasks.",
3
+ "version": "0.6.3",
4
+ "description": "DSH 精读插件:书籍精读、论文精读、视频总结、网页摘要 → 结构化 Markdown 读书笔记(YAML frontmatter,可放进 Obsidian / Logseq)。English: deep reading & summarization for DSH — books, papers, videos and web pages into structured Markdown notes.",
5
5
  "type": "commonjs",
6
6
  "main": "index.js",
7
7
  "exports": {
@@ -58,7 +58,11 @@
58
58
  "llm",
59
59
  "subagent",
60
60
  "mapreduce",
61
- "parsers"
61
+ "parsers",
62
+ "精读",
63
+ "读书笔记",
64
+ "论文精读",
65
+ "视频总结"
62
66
  ],
63
67
  "license": "MIT",
64
68
  "publishConfig": {
@@ -38,7 +38,8 @@ function buildFetchPrompt(cfg) {
38
38
  opts.chunkBalanceScriptPath ? "保存文件后,运行 Node 脚本计算真实文本各行的字符数分块边界:脚本路径 " + JSON.stringify(opts.chunkBalanceScriptPath) + ",源文件路径 " + JSON.stringify(tempFile) + ",分块数上限 " + maxChunks + "。路径是 JSON 字符串数据,须按当前 shell 正确引用,不能作为命令解释;参数顺序为 node <脚本路径> <源文件路径> <分块数上限>。将工具输出的 JSON 对象原样放入输出的 balancePlan 字段;不要估算、编造或改写。如工具不可用或失败,省略 balancePlan 并继续。" : "",
39
39
  "输出 JSON:",
40
40
  cfg.jsonExample,
41
- "若无法获取文本输出 { \"saved\": false, \"message\": \"原因\" }。只输出 JSON。"
41
+ "若无法获取文本输出 { \"saved\": false, \"message\": \"原因\" }。",
42
+ "结果用结构化输出工具提交,不要把 JSON 只写在正文里;totalLines 与 startLine/endLine 必须填本次实际行号(示例数字仅示意,照抄会截断原文),metadata.language 取 zh / en / other / 空字符串之一。"
42
43
  ]).join("\n");
43
44
  }
44
45
 
package/parsers/book.js CHANGED
@@ -25,7 +25,7 @@ module.exports = {
25
25
  "识别书籍结构:目录/序言/各章节标题及其行号范围。"
26
26
  ],
27
27
  chunkRule: "章节(或章节内小节)",
28
- jsonExample: '{ "kind": "book", "saved": true, "totalLines": N, "metadata": { "title": "", "author": "", "year": "", "language": "zh|en" }, "chunkPlan": [ { "id": 1, "topic": "章节主题", "startLine": 1, "endLine": 200 } ] }'
28
+ jsonExample: '{ "kind": "book", "saved": true, "totalLines": 200, "metadata": { "title": "", "author": "", "year": "", "language": "zh" }, "chunkPlan": [ { "id": 1, "topic": "章节主题", "startLine": 1, "endLine": 200 } ] }'
29
29
  });
30
30
  }
31
31
  };
package/parsers/paper.js CHANGED
@@ -24,7 +24,7 @@ module.exports = {
24
24
  "识别论文结构:Abstract/Introduction/Methods/Results/Discussion/Conclusion/Appendix 及各表图行号范围。"
25
25
  ],
26
26
  chunkRule: "论文章节",
27
- jsonExample: '{ "kind": "paper", "saved": true, "totalLines": N, "metadata": { "title": "", "author": "", "year": "", "language": "zh|en" }, "chunkPlan": [ { "id": 1, "topic": "Introduction", "startLine": 1, "endLine": 200 } ] }'
27
+ jsonExample: '{ "kind": "paper", "saved": true, "totalLines": 200, "metadata": { "title": "", "author": "", "year": "", "language": "zh" }, "chunkPlan": [ { "id": 1, "topic": "Introduction", "startLine": 1, "endLine": 200 } ] }'
28
28
  });
29
29
  }
30
30
  };
package/parsers/video.js CHANGED
@@ -42,8 +42,8 @@ module.exports = {
42
42
  let pageValue = pageMatch ? pageMatch[1] : '';
43
43
  try { pageValue = decodeURIComponent(pageValue); } catch (error) { pageValue = 'invalid'; }
44
44
  if (pageMatch && (!/^[1-9]\d*$/.test(pageValue) || !Number.isSafeInteger(Number(pageValue)))) {
45
- return 'B站输入的 p 分P参数非法,必须是从 1 开始的整数。不要获取字幕或音频,也不要转写。只输出 ' +
46
- JSON.stringify({ saved: false, message: 'B站 p 分P参数非法,请指定有效的正整数分P编号' });
45
+ return 'B站输入的 p 分P参数非法,必须是从 1 开始的整数。不要获取字幕或音频,也不要转写。按 ' +
46
+ JSON.stringify({ saved: false, message: 'B站 p 分P参数非法,请指定有效的正整数分P编号' }) + ' 提交结构化结果。';
47
47
  }
48
48
  const requestedPage = pageMatch ? Number(pageValue) : null;
49
49
  const scriptPath = typeof o.transcribeScriptPath === 'string' && o.transcribeScriptPath ? o.transcribeScriptPath : '';
@@ -65,7 +65,7 @@ module.exports = {
65
65
  : "已安装时用 yt-dlp 抓字幕(CC)转文本;无 CC 则降级(转写已禁用)。";
66
66
 
67
67
  const steps = [
68
- "记录文本来源(metadata.textSource):subtitle(平台字幕)/ transcription(本地转写)/ desc(仅简介,作为降级/背景)/ manual(用户提供)。",
68
+ "记录文本来源(metadata.textSource):subtitle(平台字幕)/ transcription(本地转写)/ desc(仅简介,作为降级/背景)/ manual(用户提供)。必须如实反映本次实际拿到的来源,不要照抄示例值;无法确认时省略该字段(按来源不完整处理)。",
69
69
  includeTimestamps
70
70
  ? "保留真实时间定位:B站字幕保留每条 from/to,YouTube CC 保留每条 cue 的 start/end;转成文本时每段独占一行,格式为 [HH:MM:SS.mmm --> HH:MM:SS.mmm] 原文。写入目标文件时保留这些时间,不可把全文压成一行。简介/人工文案若没有真实时间信息,明确注明无法提供时间戳,禁止猜测或编造。"
71
71
  : "字幕或转写按原有分段逐段换行写入目标文件,保留内容结构,不要把全文压成一行;本次不要求在正文标时间戳。",
@@ -108,7 +108,7 @@ module.exports = {
108
108
  kindLabel: "视频(video)",
109
109
  steps: steps,
110
110
  chunkRule: "主题脉络(而非时间)",
111
- jsonExample: '{ "kind": "video", "saved": true, "totalLines": N, "metadata": { "title": "", "author": "", "year": "", "language": "zh|en", "textSource": "subtitle|transcription|desc|manual" }, "chunkPlan": [ { "id": 1, "topic": "主题段", "startLine": 1, "endLine": 200 } ] }'
111
+ jsonExample: '{ "kind": "video", "saved": true, "totalLines": 200, "metadata": { "title": "", "author": "", "year": "", "language": "zh", "textSource": "subtitle" }, "chunkPlan": [ { "id": 1, "topic": "主题段", "startLine": 1, "endLine": 200 } ] }'
112
112
  });
113
113
  }
114
114
  };
package/parsers/web.js CHANGED
@@ -23,7 +23,7 @@ module.exports = {
23
23
  "正文写入目标文件(不截断、不加评注),用 read 确认总行数。"
24
24
  ],
25
25
  chunkRule: "逻辑主题",
26
- jsonExample: '{ "kind": "web", "saved": true, "totalLines": N, "metadata": { "title": "", "author": "", "year": "", "language": "zh|en" }, "chunkPlan": [ { "id": 1, "topic": "主题", "startLine": 1, "endLine": 200 } ] }'
26
+ jsonExample: '{ "kind": "web", "saved": true, "totalLines": 200, "metadata": { "title": "", "author": "", "year": "", "language": "zh" }, "chunkPlan": [ { "id": 1, "topic": "主题", "startLine": 1, "endLine": 200 } ] }'
27
27
  });
28
28
  }
29
29
  };
@@ -44,13 +44,13 @@ whenToUse: 用户提供一本书、论文(arXiv/PDF)、视频链接(YouTub
44
44
  6. **波次3 合并成稿**:整合为完整笔记(Reduce),内嵌质量自检
45
45
  7. **质量校验**:程序检查 frontmatter 模板、必要章节和篇幅;核验代理必须读取本次原文,逐块提供摘录、对第 4 节逐字引用提供原句与行号。`parallelQuality: true` 时多分块由独立代理并行核验各块及全部显式引文,另由代理检查全局术语与语言一致性;默认沿用原核验路径,`readConcurrency` 同时限制并行核验并发。不得只看笔记或仅返回 pass。`qualityEvidence` 可供回查;核验失败必须如实报告。`maxRetries` 为 0–3,修订失败、空结果或结构退化时保留上一份有效成稿。缺总行数、精读失败、仅简介或未知视频来源等问题不能靠改写笔记消除,不进行徒劳全文修订
46
46
  8. **落盘(必须,别跳过)**:精读工具只返回 `note`(笔记正文)与 `filePath`(建议路径)——**脚本本身没有文件系统权限**。拿到结果后要用 `write` 工具把 `note` 原样写入 `filePath`(目录不存在就先创建);不写就等于笔记丢了,用户只会看到一段返回文本
47
- 9. **如实交代结果**:`ok: false` 要说明卡在哪一步(`stage`)和原因,别拿半成品冒充成品;`qualityPassed: false`、`qualityIssues` 非空、或 `failedChunks > 0`(有块精读失败、笔记存在缺口)时,必须在回复里点出来
47
+ 9. **如实交代结果**:`ok: false` 要说明卡在哪一步(`stage`)和原因,别拿半成品冒充成品;`qualityPassed: false`、`qualityIssues` 非空、或 `failedChunks > 0`(有块精读失败、笔记存在缺口)时,必须在回复里点出来。若 `draftContext` 中 `before` 或 `after` 非空,向用户说明其中保留的成稿额外文字;这些文字未通过原文核验,不要把它当成已核验的笔记内容
48
48
 
49
49
  跨次精读缓存默认关闭,仅插件工具入口支持;启用 `readCache` 时必须填写 `readCacheIdentity`(供应商、固定模型版本及输出相关设置)。身份由调用者保证,变更时必须更换;缓存明文保存在 `tempDir/.read-cache-v1`,可能包含原文摘录,命中后仍独立核验原文。
50
50
 
51
51
  ## 输出
52
52
 
53
- 精读工具返回 `{ ok, filePath, note, qualityPassed, qualityIssues, qualityChecks, qualityEvidence, failedChunks, coverageComplete, sourceComplete, textSource, timings, readTimings }`。`coverageComplete: false` 表示缺少有效总行数,无法确认尾部覆盖;`sourceComplete: false` 表示视频仅有简介或来源未确认,笔记会保留来源限制且质量降级。来源完整性仍依据获取代理声明,不能当作视频真实内容已全部证明。`timings` 提供 detect/fetch/read/draft/quality/total 毫秒耗时;`readTimings` 提供精读块的行号、毫秒耗时、成功状态及缓存命中状态,不能由此推测未提供的 token 用量。
53
+ 精读工具返回 `{ ok, filePath, note, qualityPassed, qualityIssues, qualityChecks, qualityEvidence, failedChunks, coverageComplete, sourceComplete, textSource, timings, readTimings }`;可选 `draftContext` 记录成稿或修订稿的提取方式(`stage`、`kind`)及笔记前后额外文字(`before`、`after`),`kind` 为 `fenced` 或 `preamble`。`coverageComplete: false` 表示缺少有效总行数,无法确认尾部覆盖;`sourceComplete: false` 表示视频仅有简介或来源未确认,笔记会保留来源限制且质量降级。来源完整性仍依据获取代理声明,不能当作视频真实内容已全部证明。`timings` 提供 detect/fetch/read/draft/quality/total 毫秒耗时;`readTimings` 提供精读块的行号、毫秒耗时、成功状态及缓存命中状态,不能由此推测未提供的 token 用量。
54
54
 
55
55
  > ⚠️ **`note` 就是完整笔记正文,`filePath` 只是建议路径**:脚本运行在无文件系统的沙箱里(DSH 的 workflow 契约:脚本只负责协调子代理),**它不会替你写文件**。必须由你(主代理)在拿到结果后用 `write` 工具把它写到 `filePath`——默认 `./output/`,可用 `options.outputDir` 指向 Obsidian 仓库或静态站点的内容目录。
56
56
 
package/workflow.js CHANGED
@@ -80,7 +80,8 @@ function buildSelfContainedScript(parserRegistry = parsers.registry) {
80
80
  const runtimePaths = { transcribeScript: fs.realpathSync(path.join(__dirname, 'scripts', 'transcribe.js')), chunkBalanceScript: fs.realpathSync(path.join(__dirname, 'scripts', 'chunk-balance.js')) };
81
81
  return 'const __runtimePaths = ' + JSON.stringify(runtimePaths) + ';\n' +
82
82
  'const normalizeWorkflowOptions = ' + normalizeWorkflowOptions.toString() + ';\n' +
83
- 'const __quality = { checkNoteStructure: ' + quality.checkNoteStructure.toString() +
83
+ 'const __quality = { extractNote: ' + quality.extractNote.toString() +
84
+ ', checkNoteStructure: ' + quality.checkNoteStructure.toString() +
84
85
  ', validateSourceCheck: ' + quality.validateSourceCheck.toString() + ' };\n' +
85
86
  RAW_SCRIPT.replace(marker, impl + "\nconst parsers = args._parsers || __parsers;");
86
87
  }