dsh-knit 0.9.0 → 0.12.0

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.
@@ -0,0 +1,304 @@
1
+ /**
2
+ * Knit · **引用关系**(v0.12)
3
+ *
4
+ * 从工作区的 Markdown 里解析出「谁引用了谁」,供反向链接面板使用。
5
+ *
6
+ * ## 为什么是「宁可少,不可错」
7
+ *
8
+ * 设计依据是拿真实语料量出来的(`01_ Knit PRD/Knit_SDD-v0.12-链接解析与反向链接面板.md` §一):
9
+ *
10
+ * - `[[wikilink]]` 在真实语料里出现 **0 次** —— 所以**不解析 Obsidian 语法**,
11
+ * 真正要认的是 `` `path/x.md` ``(出现 946 次)
12
+ * - **歧义 basename 是最大误报源**:`SKILL.md` 有 20 个、`01_公众号正文.md` 有 12 个。
13
+ * 一条只写了 basename 的提及**无法确定是哪一篇** —— 而那些提及多半在讲
14
+ * 「文件名约定」而不是某一篇具体文档(实测 13% 的边是这么来的)
15
+ *
16
+ * 所以本模块**猜的一律不算**:解析不出来就是没有链接。
17
+ * 少显示一条真链接,比显示一条假链接轻。
18
+ *
19
+ * ## 这是纯解析,不碰排序
20
+ *
21
+ * 链接图当排序信号**实测补不上**词面错配那个缺口(目标文档 BM25 第 45 名 →
22
+ * 融合后 16~24 名,RRF 最好第 8,从未进 top-5)。所以这里只产出「关系」,不参与打分。
23
+ *
24
+ * ## 依赖是注入的,不 import `index.js`
25
+ *
26
+ * `index.js` 要 import 本模块来挂路由;如果本模块反过来 import 它的
27
+ * `collectDocs` / `readDocument`,就成环了。所以照 `tool.js` 的先例
28
+ * (`knitDocsDefinition(scan, read)`)**由调用方把两个函数传进来**。
29
+ * 好处不止是避环:纯函数可以拿假数据直接测,不用起文件系统。
30
+ *
31
+ * ⚠️ **已知边界**(都写在 SDD §八):不做模糊匹配、不处理 `../` 上跳、
32
+ * 不区分代码块内的「示例路径」、正文按 `readDocument` 的 512KB 上限截断。
33
+ */
34
+
35
+ /** 解析一篇正文时最多认多少条候选,防御性上限(正常文档远低于此)。 */
36
+ const MAX_REFS_PER_DOC = 500
37
+
38
+ /**
39
+ * 从正文里抽出**候选**引用(还没解析成 rel)。
40
+ *
41
+ * 三种真实写法,按语料出现频次排:
42
+ * 1. 反引号包裹的路径 —— `` `docs/A.md` ``(946 次,主力)
43
+ * 2. 标准 Markdown 链接 —— `[文字](docs/A.md)`(15 次)
44
+ * 3. 裸路径提及 —— `见 docs/A.md`(前面必须是空白或括号,避免咬到 `a.md.bak` 这类)
45
+ *
46
+ * **不含 `[[wikilink]]`** —— 真实语料 0 次,不做。
47
+ *
48
+ * @param {string} text - 正文(原文,**不是**小写化的 haystack)
49
+ * @returns {string[]} 去重后的候选项,保持出现顺序
50
+ */
51
+ export function extractRefs(text) {
52
+ if (typeof text !== 'string' || text === '') return []
53
+ const out = []
54
+ const seen = new Set()
55
+ const push = (raw) => {
56
+ const v = String(raw || '').trim()
57
+ if (!v || seen.has(v)) return
58
+ if (out.length >= MAX_REFS_PER_DOC) return
59
+ // 外链不是本工作区的文档
60
+ if (/^[a-z][a-z0-9+.-]*:/i.test(v)) return
61
+ if (!/\.md$/i.test(v)) return
62
+ seen.add(v)
63
+ out.push(v)
64
+ }
65
+
66
+ // ① 反引号:允许空格(`00_ Knit PRD/x.md` 这种目录名真实存在),不允许换行/反引号
67
+ for (const m of text.matchAll(/`([^`\n]+?)`/g)) push(m[1])
68
+ // ② Markdown 链接:取 () 里的路径,忽略其后的 #锚点
69
+ for (const m of text.matchAll(/\]\(\s*([^)\s]+?)(?:#[^)\s]*)?\s*\)/g)) push(m[1])
70
+ // ③ 裸路径:前面是行首/空白/中文括号,路径本身不含空格(有空格就得用反引号),
71
+ // 末尾用 `(?![\w.])` 挡住 `a.md.bak` 这类「更长但不是 .md」的字符串
72
+ //
73
+ // ⚠️ 必须在**挖掉反引号与链接目标之后的副本**上跑。否则
74
+ // `` `00_ Knit PRD/x.md` `` 里的 `PRD/x.md`(前面正好是空格)会被当成
75
+ // 一条独立候选 —— 这是测试抓出来的真实缺陷,不是假想。
76
+ const masked = text
77
+ .replace(/`[^`\n]*`/g, (s) => ' '.repeat(s.length))
78
+ .replace(/\]\([^)\n]*\)/g, (s) => ' '.repeat(s.length))
79
+ const BARE = /(?:^|[\s((])((?:[\w\u4e00-\u9fa5.@+-]+\/)*[\w\u4e00-\u9fa5.@+-]+\.md)(?![\w.])/gm
80
+ for (const m of masked.matchAll(BARE)) push(m[1])
81
+
82
+ return out
83
+ }
84
+
85
+ /** rel 用 `/` 连接(`index.js` 保证),所以这里也按 `/` 取目录,不碰 `node:path`。 */
86
+ const dirOf = (rel) => {
87
+ const i = String(rel).lastIndexOf('/')
88
+ return i === -1 ? '' : String(rel).slice(0, i)
89
+ }
90
+ const baseOf = (rel) => {
91
+ const s = String(rel)
92
+ const i = s.lastIndexOf('/')
93
+ return i === -1 ? s : s.slice(i + 1)
94
+ }
95
+
96
+ /**
97
+ * 为一批 rel 建解析上下文。**纯数据,可缓存**。
98
+ *
99
+ * @param {string[]} rels - 工作区里全部文档的 rel
100
+ * @returns {{relSet:Set<string>, rels:string[], byBase:Map<string,string[]>}}
101
+ */
102
+ export function createIndex(rels) {
103
+ const relSet = new Set(rels)
104
+ const byBase = new Map()
105
+ for (const rel of rels) {
106
+ const b = baseOf(rel)
107
+ if (!byBase.has(b)) byBase.set(b, [])
108
+ byBase.get(b).push(rel)
109
+ }
110
+ return { relSet, rels, byBase }
111
+ }
112
+
113
+ /**
114
+ * 把一条候选解析成工作区内的 rel,**解析不出来就返回 null**。
115
+ *
116
+ * 优先级(SDD §3.3,顺序本身就是设计):
117
+ * 1. **引用方所在目录优先** —— 这才是相对路径的语义。
118
+ * 所以 `docs/B.md` 里写 `README.md` 会先找 `docs/README.md`
119
+ * 2. 工作区根
120
+ * 3. **缩写后缀**:`-SDD-v0.6.md` 这种省略了公共前缀的写法(真实语料里存在),
121
+ * 必须**唯一命中**才算
122
+ * 4. **basename**:仅当全库该名字**唯一**时才算
123
+ * 5. 否则 → `null`(§一 的 13% 误报就是这里挡掉的)
124
+ *
125
+ * @param {string} raw - 候选项
126
+ * @param {object} index - `createIndex()` 的产物
127
+ * @param {string} [referrerRel] - 引用方的 rel;不传则跳过第 1 步
128
+ * @returns {string|null}
129
+ */
130
+ export function resolveRef(raw, index, referrerRel) {
131
+ const v = String(raw || '').trim()
132
+ if (!v || !index || !(index.relSet instanceof Set)) return null
133
+ if (/^[a-z][a-z0-9+.-]*:/i.test(v)) return null
134
+ if (!/\.md$/i.test(v)) return null
135
+
136
+ // 去掉 ./ 前缀(`./docs/A.md` 是常见写法,但不是本工作区的 rel)
137
+ const clean = v.replace(/^\.\//, '')
138
+
139
+ // ① 引用方所在目录
140
+ if (referrerRel) {
141
+ const dir = dirOf(referrerRel)
142
+ if (dir) {
143
+ const sibling = `${dir}/${clean}`
144
+ if (index.relSet.has(sibling)) return sibling
145
+ }
146
+ }
147
+
148
+ // ② 工作区根
149
+ if (index.relSet.has(clean)) return clean
150
+
151
+ // ③ 缩写后缀:只在以 `-` 开头时试,且必须唯一
152
+ if (clean.startsWith('-')) {
153
+ const tail = clean.slice(1)
154
+ const hits = index.rels.filter((r) => r.endsWith(tail))
155
+ if (hits.length === 1) return hits[0]
156
+ return null
157
+ }
158
+
159
+ // ④ basename,仅当唯一
160
+ const same = index.byBase.get(baseOf(clean))
161
+ if (same && same.length === 1) return same[0]
162
+
163
+ // ⑤ 猜不了就不算
164
+ return null
165
+ }
166
+
167
+ /** 模块内的图缓存:一个工作区一张图。key 是 `root`,值是 `{signature, graph}`。 */
168
+ const CACHE = new Map()
169
+ /** 进行中的构建,避免并发请求解析两遍。key 是 `root`。 */
170
+ const INFLIGHT = new Map()
171
+
172
+ /**
173
+ * 图签名:变了才重建。用「篇数 + 最大 mtime + 是否被扫描上限截断」——
174
+ * 三个都便宜(`list()` 本身已经按 mtime 缓存了元信息),且足以发现增删改。
175
+ */
176
+ function signatureOf(listed) {
177
+ const docs = (listed && listed.docs) || []
178
+ let max = 0
179
+ for (const d of docs) if (d.mtimeMs > max) max = d.mtimeMs
180
+ return `${docs.length}:${max}:${listed && listed.truncated ? 1 : 0}`
181
+ }
182
+
183
+ /**
184
+ * 建(或复用缓存的)引用图。
185
+ *
186
+ * @param {string} root - 工作区根
187
+ * @param {{list:Function, read:Function}} io - `list(root)` → `{docs, truncated}`;`read(root, rel)` → `{ok, text}`
188
+ * @returns {Promise<object>} `{ signature, docs:Map<rel,title>, out:Map<rel,Set>, in:Map<rel,Set>, limited, parsed, skipped }`
189
+ */
190
+ export async function buildLinkGraph(root, io) {
191
+ const listed = await io.list(root)
192
+ const signature = signatureOf(listed)
193
+ const hit = CACHE.get(root)
194
+ if (hit && hit.signature === signature) return hit.graph
195
+
196
+ const pending = INFLIGHT.get(root)
197
+ if (pending) return pending
198
+
199
+ const work = (async () => {
200
+ const docs = (listed && listed.docs) || []
201
+ const titles = new Map(docs.map((d) => [d.rel, d.title || baseOf(d.rel)]))
202
+ const index = createIndex(docs.map((d) => d.rel))
203
+ const out = new Map()
204
+ let parsed = 0
205
+ let skipped = 0
206
+
207
+ for (const doc of docs) {
208
+ let text = ''
209
+ try {
210
+ const r = await io.read(root, doc.rel)
211
+ if (!r || r.ok !== true) {
212
+ skipped += 1
213
+ continue
214
+ }
215
+ text = r.text || ''
216
+ } catch {
217
+ skipped += 1
218
+ continue
219
+ }
220
+ parsed += 1
221
+ const targets = new Set()
222
+ for (const raw of extractRefs(text)) {
223
+ const rel = resolveRef(raw, index, doc.rel)
224
+ if (rel && rel !== doc.rel) targets.add(rel)
225
+ }
226
+ out.set(doc.rel, targets)
227
+ }
228
+
229
+ // 反向边由正向边推出来,避免两处逻辑不一致
230
+ const incoming = new Map(docs.map((d) => [d.rel, new Set()]))
231
+ for (const [from, targets] of out) {
232
+ for (const to of targets) {
233
+ if (incoming.has(to)) incoming.get(to).add(from)
234
+ }
235
+ }
236
+
237
+ const graph = {
238
+ signature,
239
+ titles,
240
+ out,
241
+ in: incoming,
242
+ limited: !!(listed && listed.truncated),
243
+ parsed,
244
+ skipped,
245
+ }
246
+ CACHE.set(root, { signature, graph })
247
+ INFLIGHT.delete(root)
248
+ return graph
249
+ })()
250
+
251
+ INFLIGHT.set(root, work)
252
+ try {
253
+ return await work
254
+ } catch (err) {
255
+ INFLIGHT.delete(root)
256
+ throw err
257
+ }
258
+ }
259
+
260
+ /** 仅供测试:清掉缓存,避免用例之间互相污染。 */
261
+ export function resetLinkCache() {
262
+ CACHE.clear()
263
+ INFLIGHT.clear()
264
+ }
265
+
266
+ /** 按「对方入度降序 + rel 字典序」排 —— 引用多的文档往往是主脉络,且顺序必须稳定。 */
267
+ function orderBy(rels, graph) {
268
+ return [...rels].sort((a, b) => {
269
+ const da = (graph.in.get(a) || new Set()).size
270
+ const db = (graph.in.get(b) || new Set()).size
271
+ if (da !== db) return db - da
272
+ return a < b ? -1 : a > b ? 1 : 0
273
+ })
274
+ }
275
+
276
+ /**
277
+ * 取某一篇的引用关系。**只返回 `rel` + `title`** —— 与 `knit_docs` 同一条纪律,
278
+ * 不把图、haystack 之类的内部结构泄漏给客户端。
279
+ *
280
+ * @param {object} graph - `buildLinkGraph()` 的产物
281
+ * @param {string} rel - 目标文档
282
+ * @param {number} [limit] - 每侧最多返回多少条(计数仍给全量)
283
+ * @returns {object} 成功 `{ok:true, …}`;未知 rel 返回 `{ok:false, code:'knit/not-found'}`
284
+ */
285
+ export function linksOf(graph, rel, limit = 50) {
286
+ if (!graph || !graph.titles || !graph.titles.has(rel)) {
287
+ return { ok: false, code: 'knit/not-found' }
288
+ }
289
+ const cap = Number.isFinite(limit) && limit > 0 ? Math.trunc(limit) : 50
290
+ const map = (set) => orderBy(set || new Set(), graph)
291
+ .map((r) => ({ rel: r, title: graph.titles.get(r) || baseOf(r) }))
292
+
293
+ const incoming = map(graph.in.get(rel))
294
+ const outgoing = map(graph.out.get(rel))
295
+ return {
296
+ ok: true,
297
+ rel,
298
+ incoming: incoming.slice(0, cap),
299
+ outgoing: outgoing.slice(0, cap),
300
+ incomingTotal: incoming.length,
301
+ outgoingTotal: outgoing.length,
302
+ limited: !!graph.limited,
303
+ }
304
+ }
package/src/host/tool.js CHANGED
@@ -41,6 +41,23 @@ export const MAX_LIMIT = 20
41
41
  /** 结果里摘要再截一次(宿主的首段摘要本身是 60 字,这里防的是极端长首段)。 */
42
42
  const SUMMARY_CHARS = 90
43
43
 
44
+ /**
45
+ * 命中段落的上限(v0.11)。
46
+ *
47
+ * 取值依据是实测:`knit_docs` 一次输出约 710 字符,而**一篇文档平均 12,930 字符**。
48
+ * 每篇多 200 字 ≈ 一篇文档的 7.7%,而它想省掉的是整整一次 `read`。
49
+ * 见 `Knit_SDD-v0.11-knit_docs命中段落.md` §一。
50
+ */
51
+ const SNIPPET_CHARS = 200
52
+
53
+ /**
54
+ * 只在原文的**前 2500 字**里找命中段落。
55
+ *
56
+ * 必须与 `index.js` 的 `HAYSTACK_CHARS` 一致 —— 评分只看这个窗口,
57
+ * 若在这里找窗口外的内容,会出现「排上来了、但段落里没有命中词」的自相矛盾。
58
+ */
59
+ const SNIPPET_WINDOW = 2500
60
+
44
61
  /**
45
62
  * 模型面向的描述。**必须短** —— 它会进每一次请求的系统提示词。
46
63
  *
@@ -109,6 +126,10 @@ const OUTPUT_SCHEMA = {
109
126
  title: { type: 'string' },
110
127
  summary: { type: 'string' },
111
128
  mtimeMs: { type: 'integer' },
129
+ // v0.11:命中的那一小段**原文**(不是整篇)。**可选** ——
130
+ // 时间序模式没有命中词,抽不出来就不带这个字段,
131
+ // 而不是给个空串假装有。
132
+ snippet: { type: 'string' },
112
133
  },
113
134
  required: ['rel', 'title', 'summary', 'mtimeMs'],
114
135
  },
@@ -157,9 +178,99 @@ export function agentScope(exec) {
157
178
  * @param {unknown} text - 摘要
158
179
  * @returns {string} 单行摘要
159
180
  */
160
- function oneLine(text) {
181
+ /**
182
+ * 压成单行并截断。
183
+ *
184
+ * ⚠️ **截断上限是参数,不是常量** —— v0.11 加命中段落时踩过一次:
185
+ * 段落提取出来是 200 字,若复用只认 `SUMMARY_CHARS`(90) 的 `oneLine`,
186
+ * 会被二次截掉一半,而且**测试不会报错**(输出仍然是合法的短文本)。
187
+ *
188
+ * @param {unknown} text - 任意文本
189
+ * @param {number} cap - 上限字符数
190
+ * @returns {string} 单行文本
191
+ */
192
+ function flatten(text, cap) {
161
193
  const flat = String(text == null ? '' : text).replace(/\s+/g, ' ').trim()
162
- return flat.length > SUMMARY_CHARS ? `${flat.slice(0, SUMMARY_CHARS)}…` : flat
194
+ return flat.length > cap ? `${flat.slice(0, cap)}…` : flat
195
+ }
196
+
197
+ function oneLine(text) {
198
+ return flatten(text, SUMMARY_CHARS)
199
+ }
200
+
201
+ /**
202
+ * 从**原文**里挑出「命中的那一段」,给模型判断「要不要读整篇」用(v0.11)。
203
+ *
204
+ * 三条设计约束,每条都有原因:
205
+ *
206
+ * 1. **在原文上切,不在 `haystack` 上切。** `haystack.body` 是 `.toLowerCase()` 过的
207
+ * (`index.js:240`),在它上面切会把 `BM25` 变成 `bm25` ——
208
+ * 与「标签是你自己打的字,大小写原样保留」这条既有承诺直接冲突。
209
+ * 2. **只看前 `SNIPPET_WINDOW` 字**,与评分窗口一致,避免「排上来但段落里没命中词」。
210
+ * 3. **块太长时以命中词为中心截**,不是从头截 —— 否则命中那句话可能正好被截掉,
211
+ * 段落就白给了。
212
+ * 4. **跳过与标题重复的块。** 拿真实工作区试跑时发现的:一篇文档的 H1 标题里含全部命中词,
213
+ * 于是「命中词最多的块」就是标题本身 —— 而标题**第 1 行已经给过了**。
214
+ * 这种段落是纯浪费,正是要避免的「负收益」情形。
215
+ *
216
+ * 纯函数:不读盘、不看时钟、无副作用。抽不出命中段落时返回空串
217
+ * (**不编造** —— 「没有命中」和「命中在别处」都不该被伪装成有一段)。
218
+ *
219
+ * @param {string} text - 文档**原文**
220
+ * @param {string[]} terms - 命中词(来自 `scan()` 的 `keywords`,即语料里真实存在的词)
221
+ * @param {{title?: string}} [options] - `title` 用于排除「与标题重复」的块
222
+ * @returns {string} 命中段落(已压成单行、截断),或空串
223
+ */
224
+ export function pickSnippet(text, terms, options = {}) {
225
+ const source = String(text == null ? '' : text)
226
+ const words = (Array.isArray(terms) ? terms : [])
227
+ .map((term) => String(term == null ? '' : term).trim().toLowerCase())
228
+ .filter(Boolean)
229
+ if (!source || words.length === 0) return ''
230
+
231
+ // 归一化只用于**比较**:去掉 Markdown 标题号、强调号、表格竖线,压平空白,小写
232
+ const norm = (s) => String(s).replace(/[#*|`>\s]+/g, ' ').trim().toLowerCase()
233
+ const titleNorm = norm(options.title || '')
234
+
235
+ const window = source.slice(0, SNIPPET_WINDOW)
236
+
237
+ // 按空行切块 —— 纯字符串运算,不解析 Markdown 结构
238
+ const blocks = window.split(/\n\s*\n/).map((block) => block.trim()).filter(Boolean)
239
+ if (blocks.length === 0) return ''
240
+
241
+ // 选**命中词种数最多**的那块;并列取靠前的(不给后面的块不该有的优势)
242
+ const scored = blocks.map((block) => {
243
+ const lower = block.toLowerCase()
244
+ let hits = 0
245
+ for (const word of words) if (lower.includes(word)) hits += 1
246
+ return { block, hits, norm: norm(block) }
247
+ })
248
+
249
+ // 跳过「与标题重复」的块(见 JSDoc 第 4 条)
250
+ const usable = scored.filter((item) => !(titleNorm && item.norm && titleNorm.includes(item.norm)))
251
+ if (usable.length === 0) return ''
252
+
253
+ let best = null
254
+ for (const item of usable) {
255
+ if (item.hits > 0 && (best === null || item.hits > best.hits)) best = item
256
+ }
257
+ // 一块都没命中 → 返回空串,而不是退化成「随便给第一段」
258
+ if (best === null) return ''
259
+
260
+ const flat = best.block.replace(/\s+/g, ' ').trim()
261
+ if (flat.length <= SNIPPET_CHARS) return flat
262
+
263
+ const lowerFlat = flat.toLowerCase()
264
+ let at = -1
265
+ for (const word of words) {
266
+ const found = lowerFlat.indexOf(word)
267
+ if (found >= 0 && (at < 0 || found < at)) at = found
268
+ }
269
+ const maxStart = flat.length - SNIPPET_CHARS
270
+ const start = at < 0 ? 0 : Math.max(0, Math.min(at - Math.floor(SNIPPET_CHARS / 3), maxStart))
271
+ const head = start > 0 ? '…' : ''
272
+ const tail = start < maxStart ? '…' : ''
273
+ return `${head}${flat.slice(start, start + SNIPPET_CHARS).trim()}${tail}`
163
274
  }
164
275
 
165
276
  /**
@@ -193,7 +304,13 @@ export function renderToolText(value) {
193
304
 
194
305
  const lines = docs.map((doc, index) => {
195
306
  const summary = oneLine(doc.summary)
196
- return `${index + 1}. ${doc.rel} — ${doc.title}${summary ? `\n ${summary}` : ''}`
307
+ // 命中段落(v0.11):给模型判断「要不要读整篇」用。
308
+ // 用一个 `match:` 前缀把它和**首段摘要**区分开 —— 两者都是一行压平的文本,
309
+ // 不加标记的话模型分不清哪行是什么。
310
+ const snippet = doc.snippet ? flatten(doc.snippet, SNIPPET_CHARS) : ''
311
+ return `${index + 1}. ${doc.rel} — ${doc.title}`
312
+ + `${summary ? `\n ${summary}` : ''}`
313
+ + `${snippet ? `\n match: ${snippet}` : ''}`
197
314
  })
198
315
 
199
316
  return [head, ...lines].join('\n')
@@ -205,9 +322,35 @@ export function renderToolText(value) {
205
322
  * 形状与官方 `defineTool(...)` 的产物一致:`{ name, description, parameters, output, execute }`。
206
323
  *
207
324
  * @param {Function} scan - 宿主的扫描函数(注入进来,避免 index.js ↔ tool.js 循环 import)
325
+ * @param {Function} [read] - 宿主的单篇读取函数 `readDocument(root, rel)`。
326
+ * **同样注入**,理由与 `scan` 一样。**可选** —— 没给就只是不带命中段落,
327
+ * `knit_docs` 的其余行为一字不变(老调用方不会坏)。
208
328
  * @returns {object} 工具定义
209
329
  */
210
- export function knitDocsDefinition(scan) {
330
+ export function knitDocsDefinition(scan, read) {
331
+ /**
332
+ * 给一篇文档抽命中段落。
333
+ *
334
+ * **任何失败都咽掉并返回空串** —— 抽不出段落只是少一条信息,
335
+ * 不该让整次工具调用失败(工具已经拿到了排序结果,那才是主要产出)。
336
+ *
337
+ * @param {string} root - 工作区根
338
+ * @param {string} rel - 相对路径
339
+ * @param {string[]} terms - 命中词
340
+ * @param {string} title - 这一篇的标题(用于排除「与标题重复」的块)
341
+ * @returns {Promise<string>} 命中段落或空串
342
+ */
343
+ async function snippetFor(root, rel, terms, title) {
344
+ if (typeof read !== 'function' || !rel || terms.length === 0) return ''
345
+ try {
346
+ const doc = await read(root, rel)
347
+ if (!doc || doc.ok !== true) return ''
348
+ return pickSnippet(doc.text, terms, { title })
349
+ } catch {
350
+ return ''
351
+ }
352
+ }
353
+
211
354
  return {
212
355
  name: TOOL_NAME,
213
356
  description: DESCRIPTION,
@@ -235,18 +378,32 @@ export function knitDocsDefinition(scan) {
235
378
  query,
236
379
  })
237
380
 
381
+ // 命中词用 `scan()` 的 `keywords` —— 它是**语料里真实存在**的那批词
382
+ // (不是原始候选),所以拿它去原文里找段落,必然找得到。
383
+ // 时间序模式下它是空数组 ⇒ terms 为空 ⇒ 不抽段落,正合语义。
384
+ const terms = Array.isArray(payload.keywords) ? payload.keywords : []
385
+
386
+ const docs = await Promise.all((payload.docs || []).map(async (doc) => {
387
+ const row = {
388
+ rel: String(doc.rel || ''),
389
+ title: String(doc.title || ''),
390
+ summary: doc.summary == null ? '' : String(doc.summary),
391
+ mtimeMs: Number.isFinite(doc.mtimeMs) ? Math.trunc(doc.mtimeMs) : 0,
392
+ }
393
+ const snippet = await snippetFor(root, row.rel, terms, row.title)
394
+ // 抽不到就**不带这个字段**,不写空串 —— 让「没有命中」和「命中但没抽出来」
395
+ // 在输出里都是「没有 match 行」,而不是一行空的 `match: `
396
+ if (snippet) row.snippet = snippet
397
+ return row
398
+ }))
399
+
238
400
  return {
239
401
  mode: payload.mode === 'relevance' ? 'relevance' : 'time',
240
402
  topic: typeof payload.topic === 'string' ? payload.topic : '',
241
403
  // `scan()` 的 total 是**全量池子**的条数(在 limit 切片之前),
242
404
  // 正好是这里要的「工作区一共有多少篇」。
243
405
  total: Number.isInteger(payload.total) ? payload.total : 0,
244
- docs: (payload.docs || []).map((doc) => ({
245
- rel: String(doc.rel || ''),
246
- title: String(doc.title || ''),
247
- summary: doc.summary == null ? '' : String(doc.summary),
248
- mtimeMs: Number.isFinite(doc.mtimeMs) ? Math.trunc(doc.mtimeMs) : 0,
249
- })),
406
+ docs,
250
407
  }
251
408
  },
252
409
  }
@@ -259,8 +416,9 @@ export function knitDocsDefinition(scan) {
259
416
  *
260
417
  * @param {object} ctx - cordis 上下文(带 `tools` 服务)
261
418
  * @param {Function} scan - 宿主的扫描函数
419
+ * @param {Function} [read] - 宿主的单篇读取函数(抽命中段落用;可选)
262
420
  * @returns {() => void} 注销函数
263
421
  */
264
- export function registerKnitDocsTool(ctx, scan) {
265
- return ctx.tools.register(knitDocsDefinition(scan))
422
+ export function registerKnitDocsTool(ctx, scan, read) {
423
+ return ctx.tools.register(knitDocsDefinition(scan, read))
266
424
  }