dsh-knit 0.19.1 → 0.20.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.
- package/CHANGELOG.md +249 -0
- package/README.en.md +41 -24
- package/README.md +32 -21
- package/SECURITY.md +2 -2
- package/package.json +3 -2
- package/src/client/client.js +742 -63
- package/src/host/context.js +29 -1
- package/src/host/index.js +124 -13
- package/src/host/passage.js +408 -0
- package/src/host/tool.js +104 -23
- package/test/client.test.mjs +793 -12
- package/test/context/fixture.mjs +2 -5
- package/test/deep-context.test.mjs +447 -0
- package/test/deep-eval.test.mjs +90 -0
- package/test/deep-scale.test.mjs +64 -0
- package/test/eval/deep.mjs +322 -0
- package/test/eval/fixture.mjs +6 -9
- package/test/fixture.mjs +21 -1
- package/test/harness.mjs +63 -4
- package/test/host.test.mjs +2 -2
- package/test/icon.test.mjs +11 -8
- package/test/tool.test.mjs +247 -18
|
@@ -0,0 +1,408 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Knit · 内容片段层(v0.20 Deep Context Retrieval)
|
|
3
|
+
*
|
|
4
|
+
* 这一层只回答一个问题:**一篇文件的正文里,哪几段与当前任务有关?**
|
|
5
|
+
*
|
|
6
|
+
* 三条边界(需求 §6 / §24):
|
|
7
|
+
* - 零模型、零网络、零依赖:全部是字符串操作
|
|
8
|
+
* - **不引入 AST / LSP / Tree-sitter**:切段靠行级正则、空行与大括号,不靠语法树
|
|
9
|
+
* - **不新建第二套检索器**:片段排序复用 `relevance.js` 的 `rankByRelevance()`
|
|
10
|
+
*
|
|
11
|
+
* 最要紧的设计是「片段是**投影**,不是第二个排序阶段」(实现说明 D3):
|
|
12
|
+
* 文件名次仍完全由现有的文件级 BM25 决定(正文不再截断,于是 `avgdl[body]`
|
|
13
|
+
* 是真实长度,长文件被 `b = 0.75` 直接惩罚),片段只在**已经排好序的文件内部**
|
|
14
|
+
* 挑最好的 1–2 段。于是「20 个低价值片段堆出一个高分文件」在结构上不可能发生
|
|
15
|
+
* (需求 §8 / §9),`test/eval.test.mjs` 那套质量基线也逐字不受影响。
|
|
16
|
+
*
|
|
17
|
+
* 行号与偏移量的口径(§11):
|
|
18
|
+
* - `startLine` / `endLine` 是 **1 起算、两端都含**的行号
|
|
19
|
+
* - `startOffset` / `endOffset` 是**原文**(不是小写 haystack)上的字符偏移,
|
|
20
|
+
* 且恒有 `body.slice(startOffset, endOffset) === 片段文本`
|
|
21
|
+
* - 片段文本**不含**结尾换行 —— 于是上面那条恒等式逐字成立,可以被测试直接断言
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
import { rankByRelevance } from './relevance.js'
|
|
25
|
+
import { KIND_CODE } from './classification.js'
|
|
26
|
+
|
|
27
|
+
/** 单个片段的目标上限(§5:结构优先,长度兜底)。 */
|
|
28
|
+
export const PASSAGE_MAX_CHARS = 1200
|
|
29
|
+
/** 片段的目标下限,短于此的相邻片段会被合并(标题、单行声明不该各占一个片段)。 */
|
|
30
|
+
export const PASSAGE_MIN_CHARS = 300
|
|
31
|
+
/** 每篇文件最多报几段(§8:限制片段数,别让一篇文件刷屏)。 */
|
|
32
|
+
export const PASSAGE_MAX_PER_FILE = 2
|
|
33
|
+
/**
|
|
34
|
+
* 只为排名最前的多少条记录建片段。
|
|
35
|
+
*
|
|
36
|
+
* 与列表分页无关:这是**宿主**这边的成本上限 —— 1000 篇文件全部切段
|
|
37
|
+
* 是 O(全文),而我们只需要前若干条的片段(§16 的「更精准而不是发更多内容」)。
|
|
38
|
+
*/
|
|
39
|
+
export const PASSAGE_WINDOW = 24
|
|
40
|
+
/** 一篇文件最多产出多少片段,超出截断(防止一个巨文件把内存吃光)。 */
|
|
41
|
+
export const PASSAGE_LINES_MAX = 200
|
|
42
|
+
/** 片段摘要的长度(与 `tool.js` 的 `SNIPPET_CHARS` 是同一个展示口径)。 */
|
|
43
|
+
export const SNIPPET_CHARS = 200
|
|
44
|
+
|
|
45
|
+
/** 超长单行按字符硬切时的重叠量:避免一个词正好落在切缝上被两边各切一半。 */
|
|
46
|
+
const HARD_SPLIT_OVERLAP = 64
|
|
47
|
+
/** 代码没有任何结构化锚点时的兜底窗口行数。 */
|
|
48
|
+
const CODE_WINDOW_LINES = 40
|
|
49
|
+
|
|
50
|
+
/** Markdown 的分段锚点:H1–H6。 */
|
|
51
|
+
const MD_HEADING = /^#{1,6}\s/
|
|
52
|
+
/**
|
|
53
|
+
* 代码的分段锚点(§5)—— **只看行首**,于是只认顶层声明,
|
|
54
|
+
* 函数内部的 `const` / `return` 不会把一段函数切碎。
|
|
55
|
+
*
|
|
56
|
+
* `}` **不是**锚点:锚点的语义是「新片段从这里**开始**」,
|
|
57
|
+
* 把收尾大括号当锚点会让片段从上一段的 `}` 开始(命中在 beta 里、
|
|
58
|
+
* 片段却从 alpha 的闭括号报起),反而不像「函数附近」。
|
|
59
|
+
*/
|
|
60
|
+
const CODE_ANCHOR = /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|const|let|var|interface|type|enum|import|export|def|from)\b/
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* 把正文切成片段。
|
|
64
|
+
*
|
|
65
|
+
* @param {string} text - **原文**(不是小写化的 haystack)
|
|
66
|
+
* @param {{kind?: string}} [options] - `kind` 为 `KIND_CODE` 时走代码口径,否则走 Markdown 口径
|
|
67
|
+
* @returns {{passages: Array<{startLine:number, endLine:number, startOffset:number,
|
|
68
|
+
* endOffset:number, text:string, body:string}>, truncated: boolean}}
|
|
69
|
+
*/
|
|
70
|
+
export function chunkText(text, options = {}) {
|
|
71
|
+
const src = typeof text === 'string' ? text : ''
|
|
72
|
+
if (src.trim() === '') return { passages: [], truncated: false }
|
|
73
|
+
const kind = options.kind === KIND_CODE ? 'code' : 'doc'
|
|
74
|
+
|
|
75
|
+
const lines = src.split('\n')
|
|
76
|
+
const offsets = new Array(lines.length)
|
|
77
|
+
let at = 0
|
|
78
|
+
for (let i = 0; i < lines.length; i++) {
|
|
79
|
+
offsets[i] = at
|
|
80
|
+
at += lines[i].length + 1
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
// 结构优先:先按结构锚点把文件切成若干「节」,再用长度兜底把过长的节切开。
|
|
84
|
+
const bounds = [0]
|
|
85
|
+
for (const c of cutsOf(lines, kind)) {
|
|
86
|
+
if (c > 0 && c < lines.length && c > bounds[bounds.length - 1]) bounds.push(c)
|
|
87
|
+
}
|
|
88
|
+
bounds.push(lines.length)
|
|
89
|
+
|
|
90
|
+
const raw = []
|
|
91
|
+
for (let i = 0; i < bounds.length - 1; i++) {
|
|
92
|
+
const a = bounds[i]
|
|
93
|
+
const z = bounds[i + 1] - 1
|
|
94
|
+
if (z < a) continue
|
|
95
|
+
pushRanges(raw, lines, offsets, a, z, PASSAGE_MAX_CHARS, PASSAGE_MIN_CHARS)
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
const merged = mergeRanges(raw, PASSAGE_MIN_CHARS, PASSAGE_MAX_CHARS)
|
|
99
|
+
const truncated = merged.length > PASSAGE_LINES_MAX
|
|
100
|
+
const kept = truncated ? merged.slice(0, PASSAGE_LINES_MAX) : merged
|
|
101
|
+
return { passages: kept.map((r) => toPassage(src, r)), truncated }
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* 给一条**已经排好名次**的文件记录挑出最相关的 1–2 段。
|
|
106
|
+
*
|
|
107
|
+
* ⚠️ 只在文件内部排序,不改文件名次(D3)。没有正文、没有关键词、或一段都没命中时
|
|
108
|
+
* 老实返回空数组 —— 空数组是「没有可报的片段」,不是「不相关」。
|
|
109
|
+
*
|
|
110
|
+
* @param {object} entry - 内部记录(需要 `body` / `kind` / `rel` / `mtimeMs`)
|
|
111
|
+
* @param {Array<{term:string, weight:number}>} keywords - 与文件级打分同一批关键词
|
|
112
|
+
* @param {number} [now] - 时间基准(确定性测试要传固定值)
|
|
113
|
+
* @returns {Array<{startLine:number, endLine:number, startOffset:number, endOffset:number,
|
|
114
|
+
* terms:Array<string>, snippet:string}>}
|
|
115
|
+
*/
|
|
116
|
+
export function passageMatchesFor(entry, keywords, now = Date.now()) {
|
|
117
|
+
if (!entry || typeof entry.body !== 'string' || entry.body === '') return []
|
|
118
|
+
if (!Array.isArray(keywords) || keywords.length === 0) return []
|
|
119
|
+
|
|
120
|
+
const { passages } = chunkText(entry.body, { kind: entry.kind })
|
|
121
|
+
if (passages.length === 0) return []
|
|
122
|
+
|
|
123
|
+
const rel = typeof entry.rel === 'string' ? entry.rel : ''
|
|
124
|
+
// 片段在这里被当成一条「文档」喂给现成的 `rankByRelevance()`:
|
|
125
|
+
// title / summary 留空,整段正文进 body(权重 1,与文件级正文同一个字段口径)。
|
|
126
|
+
const docs = passages.map((p, i) => ({
|
|
127
|
+
rel: `${rel}#${i}`,
|
|
128
|
+
name: entry.name || '',
|
|
129
|
+
title: '',
|
|
130
|
+
summary: '',
|
|
131
|
+
mtimeMs: entry.mtimeMs || 0,
|
|
132
|
+
kind: entry.kind,
|
|
133
|
+
haystack: { title: '', summary: '', body: p.body },
|
|
134
|
+
passage: p,
|
|
135
|
+
}))
|
|
136
|
+
|
|
137
|
+
const ranked = rankByRelevance(docs, keywords, now)
|
|
138
|
+
const hit = ranked.docs.filter((d) => d.raw > 0)
|
|
139
|
+
// 显式定序(§20):分数 → 行号 → 偏移 → rel。
|
|
140
|
+
// `rankByRelevance` 的末位并列判据是 `rel`,而这里的 `rel` 带着 `#下标` 后缀,
|
|
141
|
+
// 字典序会把 `#10` 排到 `#2` 前面 —— 所以这里必须自己定序,不依赖那一条。
|
|
142
|
+
hit.sort((a, b) =>
|
|
143
|
+
b.raw - a.raw
|
|
144
|
+
|| a.passage.startLine - b.passage.startLine
|
|
145
|
+
|| a.passage.startOffset - b.passage.startOffset
|
|
146
|
+
|| (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0))
|
|
147
|
+
|
|
148
|
+
// **先按分数选出最好的 1–2 段,再把选中的这几段按行号升序报出去。**
|
|
149
|
+
// 两件事要分开:分数决定「哪几段值得报」,行号决定「报出来的阅读顺序」——
|
|
150
|
+
// 读者在预览里从上往下看,片段就该按文档顺序排(§11 的「稳定确定」由前者保证)。
|
|
151
|
+
const picked = hit.slice(0, PASSAGE_MAX_PER_FILE)
|
|
152
|
+
picked.sort((a, b) =>
|
|
153
|
+
a.passage.startLine - b.passage.startLine
|
|
154
|
+
|| a.passage.startOffset - b.passage.startOffset
|
|
155
|
+
|| (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0))
|
|
156
|
+
|
|
157
|
+
return picked.map((d) => ({
|
|
158
|
+
startLine: d.passage.startLine,
|
|
159
|
+
endLine: d.passage.endLine,
|
|
160
|
+
startOffset: d.passage.startOffset,
|
|
161
|
+
endOffset: d.passage.endOffset,
|
|
162
|
+
terms: d.matchedTerms.map((t) => t.term),
|
|
163
|
+
snippet: snippetOf(d.passage.text, d.matchedTerms),
|
|
164
|
+
}))
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* 在原文上取一小段可读的摘要,以**第一个命中词**为中心。
|
|
169
|
+
*
|
|
170
|
+
* 与 `tool.js` 的 `pickSnippet` 是同一套展示口径(先压平空白再截),
|
|
171
|
+
* 区别只在于这里切的是**片段**而不是整篇正文的首部窗口。
|
|
172
|
+
*
|
|
173
|
+
* @param {string} text - 片段原文
|
|
174
|
+
* @param {Array<{term:string}>} matchedTerms - 该片段的命中词
|
|
175
|
+
* @returns {string} 不超过 `SNIPPET_CHARS` 字符的摘要(截断处用 `…` 标出)
|
|
176
|
+
*/
|
|
177
|
+
export function snippetOf(text, matchedTerms) {
|
|
178
|
+
const flat = String(text || '').replace(/\s+/g, ' ').trim()
|
|
179
|
+
if (flat === '') return ''
|
|
180
|
+
const lower = flat.toLowerCase()
|
|
181
|
+
|
|
182
|
+
let centre = -1
|
|
183
|
+
for (const t of matchedTerms || []) {
|
|
184
|
+
const term = String(t && t.term ? t.term : '').toLowerCase()
|
|
185
|
+
if (term === '') continue
|
|
186
|
+
const pos = lower.indexOf(term)
|
|
187
|
+
if (pos >= 0 && (centre < 0 || pos < centre)) centre = pos
|
|
188
|
+
}
|
|
189
|
+
if (centre < 0) centre = 0
|
|
190
|
+
|
|
191
|
+
const start = Math.max(0, centre - 40)
|
|
192
|
+
let out = flat.slice(start, start + SNIPPET_CHARS)
|
|
193
|
+
if (start > 0) out = `…${out}`
|
|
194
|
+
if (start + SNIPPET_CHARS < flat.length) out = `${out}…`
|
|
195
|
+
return out
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/**
|
|
199
|
+
* 一个词在**任意一段 `window` 字符宽的窗口内**最多出现几次。
|
|
200
|
+
*
|
|
201
|
+
* 这是修「长文件污染」的那个长度无关的量(需求 §9):整篇字频会随文件变长
|
|
202
|
+
* 而虚高 —— 29 000 字的 CHANGELOG 里一个词出现 3 次,看起来比 400 字的短文里
|
|
203
|
+
* 出现 4 次还「更像在讲它」;但把窗口收窄到一段,3 次散在三处只有 1 次,
|
|
204
|
+
* 而 4 次挤在一段里就是 4 次。`context.js` 的 `isDocHit` 用它替代整篇字频。
|
|
205
|
+
*
|
|
206
|
+
* 纯函数、零 I/O、上界确定:滑动窗口是 O(出现次数),出现次数再多数到 `cap` 次就停。
|
|
207
|
+
*
|
|
208
|
+
* @param {string} text - **已小写化**的正文(`haystack.body`)
|
|
209
|
+
* @param {string} term - **已小写化**的词
|
|
210
|
+
* @param {number} [window] - 窗口宽度(字符),默认与片段上限一致
|
|
211
|
+
* @param {number} [cap] - 最多数到几次(病态的重复文本不至于吃掉内存)
|
|
212
|
+
* @returns {number} 单窗口内的最大出现次数(0 表示没出现)
|
|
213
|
+
*/
|
|
214
|
+
export function windowTf(text, term, window = PASSAGE_MAX_CHARS, cap = 32) {
|
|
215
|
+
if (typeof text !== 'string' || text === '') return 0
|
|
216
|
+
if (typeof term !== 'string' || term === '') return 0
|
|
217
|
+
if (!Number.isFinite(window) || window <= 0) return 0
|
|
218
|
+
|
|
219
|
+
// 与 `relevance.js` 的 `countOccurrences()` 同一个口径:切完就跳过整个词
|
|
220
|
+
// (不做重叠计数),否则 'aa' 在 'aaa' 里会数出 2 次。
|
|
221
|
+
const at = []
|
|
222
|
+
let from = 0
|
|
223
|
+
for (;;) {
|
|
224
|
+
const i = text.indexOf(term, from)
|
|
225
|
+
if (i < 0) break
|
|
226
|
+
at.push(i)
|
|
227
|
+
if (at.length >= cap) break
|
|
228
|
+
from = i + term.length
|
|
229
|
+
}
|
|
230
|
+
if (at.length === 0) return 0
|
|
231
|
+
|
|
232
|
+
let best = 0
|
|
233
|
+
let left = 0
|
|
234
|
+
for (let right = 0; right < at.length; right++) {
|
|
235
|
+
while (at[right] - at[left] + term.length > window) left += 1
|
|
236
|
+
const span = right - left + 1
|
|
237
|
+
if (span > best) best = span
|
|
238
|
+
}
|
|
239
|
+
return best
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/**
|
|
243
|
+
* 给**一条已经排好名次的记录**算逐词的「单窗口内最大字频」(D5)。
|
|
244
|
+
*
|
|
245
|
+
* 只算**正文真的命中**的那些词(`matchedTerms[].fields.body`)—— 别的词本来
|
|
246
|
+
* 就不会被 `isDocHit` 看一眼,算了也是白算。没有正文(媒体)或一个词都没命中
|
|
247
|
+
* 正文时返回 `null`,于是 `context.js` 会退回 v0.19 的整篇字频口径。
|
|
248
|
+
*
|
|
249
|
+
* @param {object} doc - `rankByRelevance()` 产出的记录(含 `haystack` / `matchedTerms`)
|
|
250
|
+
* @param {number} [window] - 窗口宽度,默认与片段上限一致
|
|
251
|
+
* @returns {Object<string, number>|null}
|
|
252
|
+
*/
|
|
253
|
+
export function passageTfOf(doc, window = PASSAGE_MAX_CHARS) {
|
|
254
|
+
const hay = doc && doc.haystack ? doc.haystack : null
|
|
255
|
+
const body = hay && typeof hay.body === 'string' ? hay.body : ''
|
|
256
|
+
if (body === '') return null
|
|
257
|
+
const terms = Array.isArray(doc.matchedTerms) ? doc.matchedTerms : []
|
|
258
|
+
const out = {}
|
|
259
|
+
let any = false
|
|
260
|
+
for (const entry of terms) {
|
|
261
|
+
if (!entry || !entry.fields || !entry.fields.body) continue
|
|
262
|
+
const term = typeof entry.term === 'string' ? entry.term : ''
|
|
263
|
+
if (term === '') continue
|
|
264
|
+
out[term] = windowTf(body, term, window)
|
|
265
|
+
any = true
|
|
266
|
+
}
|
|
267
|
+
return any ? out : null
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
/* ── 内部:分段 ──────────────────────────────────────── */
|
|
271
|
+
|
|
272
|
+
/** 结构锚点所在的行下标(1 起,不包含第 0 行)。 */
|
|
273
|
+
function cutsOf(lines, kind) {
|
|
274
|
+
const out = []
|
|
275
|
+
if (kind === 'doc') {
|
|
276
|
+
for (let i = 1; i < lines.length; i++) {
|
|
277
|
+
if (MD_HEADING.test(lines[i])) out.push(i)
|
|
278
|
+
}
|
|
279
|
+
return out
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
for (let i = 1; i < lines.length; i++) {
|
|
283
|
+
if (CODE_ANCHOR.test(lines[i])) out.push(i)
|
|
284
|
+
}
|
|
285
|
+
// 结构化锚点太少(没有顶层声明的数据文件、一段散文式脚本):
|
|
286
|
+
// 退回固定行窗口,保证「长文件一定被切成多段」而不是硬撑成一整段。
|
|
287
|
+
if (out.length < 2 && lines.length > CODE_WINDOW_LINES) {
|
|
288
|
+
out.length = 0
|
|
289
|
+
for (let i = CODE_WINDOW_LINES; i < lines.length; i += CODE_WINDOW_LINES) out.push(i)
|
|
290
|
+
}
|
|
291
|
+
return out
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/** 行区间 → 带字符偏移的区间(`endOffset` 不含结尾换行;首尾空行不算内容)。 */
|
|
295
|
+
function makeRange(lines, offsets, a, z) {
|
|
296
|
+
// 首尾的空行不算内容:不剥掉的话每个片段都会顶着上一段留下的空行开头,
|
|
297
|
+
// 而 `snippetOf()` 又要先压平空白 —— 那是在为切分的毛边反复擦屁股。
|
|
298
|
+
while (a < z && lines[a].length === 0) a += 1
|
|
299
|
+
while (z > a && lines[z].length === 0) z -= 1
|
|
300
|
+
return {
|
|
301
|
+
start: a,
|
|
302
|
+
end: z,
|
|
303
|
+
startOffset: offsets[a],
|
|
304
|
+
endOffset: offsets[z] + lines[z].length,
|
|
305
|
+
}
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
/**
|
|
309
|
+
* 把一个「节」(行区间 `[a, z]`)按长度上限切开。
|
|
310
|
+
*
|
|
311
|
+
* 两处细节是刻意的:
|
|
312
|
+
* - 优先在**本段内最后一个空行**处断(§5 的 paragraph 切分),空行落在段首时不用它
|
|
313
|
+
* - 单行本身就超过上限时(压缩过的 JSON、打包产物)按字符硬切,
|
|
314
|
+
* 切缝留 `HARD_SPLIT_OVERLAP` 个字符的重叠,免得一个词被切缝劈成两半而漏掉
|
|
315
|
+
*/
|
|
316
|
+
function pushRanges(out, lines, offsets, a, z, maxChars, minChars) {
|
|
317
|
+
let start = a
|
|
318
|
+
let size = 0
|
|
319
|
+
let lastBlank = -1
|
|
320
|
+
|
|
321
|
+
const flush = (end) => {
|
|
322
|
+
if (end < start) return
|
|
323
|
+
out.push(makeRange(lines, offsets, start, end))
|
|
324
|
+
start = end + 1
|
|
325
|
+
size = 0
|
|
326
|
+
lastBlank = -1
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
for (let i = a; i <= z; i++) {
|
|
330
|
+
const lineLen = lines[i].length
|
|
331
|
+
|
|
332
|
+
if (lineLen > maxChars) {
|
|
333
|
+
if (i > start) flush(i - 1)
|
|
334
|
+
pushHardSplit(out, lines, offsets, i, maxChars)
|
|
335
|
+
start = i + 1
|
|
336
|
+
size = 0
|
|
337
|
+
lastBlank = -1
|
|
338
|
+
continue
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
const add = lineLen + 1
|
|
342
|
+
if (size > 0 && size + add > maxChars) {
|
|
343
|
+
// ③ 优先在**本段内最后一个空行**处断(§5 的 paragraph 切分)。
|
|
344
|
+
// 但只有那个空行确实够靠后(切出来的前半段已经达到下限)才用它 ——
|
|
345
|
+
// 否则一段没有空行的长正文会被切出一个只有几行的碎片。
|
|
346
|
+
const usable = lastBlank > start && offsets[lastBlank] - offsets[start] >= minChars
|
|
347
|
+
const at = usable ? lastBlank : i - 1
|
|
348
|
+
flush(at)
|
|
349
|
+
// `flush(at)` 只把 `start` 推到 `at + 1`:`at + 1 .. i - 1` 这几行已经属于
|
|
350
|
+
// 新片段,长度要重新累计(它们不可能超过一个片段,循环是有界的)。
|
|
351
|
+
for (let j = start; j < i; j++) {
|
|
352
|
+
size += lines[j].length + 1
|
|
353
|
+
if (lines[j].length === 0) lastBlank = j
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
size += add
|
|
357
|
+
if (lineLen === 0) lastBlank = i
|
|
358
|
+
}
|
|
359
|
+
if (start <= z) flush(z)
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
/** 超长单行按字符硬切(行号不变,靠偏移量区分)。 */
|
|
363
|
+
function pushHardSplit(out, lines, offsets, i, maxChars) {
|
|
364
|
+
const line = lines[i]
|
|
365
|
+
const step = Math.max(1, maxChars - HARD_SPLIT_OVERLAP)
|
|
366
|
+
let at = 0
|
|
367
|
+
while (at < line.length) {
|
|
368
|
+
const take = Math.min(maxChars, line.length - at)
|
|
369
|
+
out.push({
|
|
370
|
+
start: i,
|
|
371
|
+
end: i,
|
|
372
|
+
startOffset: offsets[i] + at,
|
|
373
|
+
endOffset: offsets[i] + at + take,
|
|
374
|
+
})
|
|
375
|
+
if (at + take >= line.length) break
|
|
376
|
+
at += step
|
|
377
|
+
}
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
/** 把过短的相邻片段并起来(只在合并后仍不超上限时)。 */
|
|
381
|
+
function mergeRanges(ranges, minChars, maxChars) {
|
|
382
|
+
const out = []
|
|
383
|
+
for (const r of ranges) {
|
|
384
|
+
const prev = out[out.length - 1]
|
|
385
|
+
const len = r.endOffset - r.startOffset
|
|
386
|
+
const prevLen = prev ? prev.endOffset - prev.startOffset : 0
|
|
387
|
+
if (prev && prevLen < minChars && prevLen + len + 1 <= maxChars) {
|
|
388
|
+
prev.end = r.end
|
|
389
|
+
prev.endOffset = r.endOffset
|
|
390
|
+
continue
|
|
391
|
+
}
|
|
392
|
+
out.push({ start: r.start, end: r.end, startOffset: r.startOffset, endOffset: r.endOffset })
|
|
393
|
+
}
|
|
394
|
+
return out
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
/** 区间 → 公开片段(行号转 1 起算,附小写正文供打分)。 */
|
|
398
|
+
function toPassage(src, r) {
|
|
399
|
+
const text = src.slice(r.startOffset, r.endOffset)
|
|
400
|
+
return {
|
|
401
|
+
startLine: r.start + 1,
|
|
402
|
+
endLine: r.end + 1,
|
|
403
|
+
startOffset: r.startOffset,
|
|
404
|
+
endOffset: r.endOffset,
|
|
405
|
+
text,
|
|
406
|
+
body: text.toLowerCase(),
|
|
407
|
+
}
|
|
408
|
+
}
|
package/src/host/tool.js
CHANGED
|
@@ -51,21 +51,27 @@ const SUMMARY_CHARS = 90
|
|
|
51
51
|
const SNIPPET_CHARS = 200
|
|
52
52
|
|
|
53
53
|
/**
|
|
54
|
-
*
|
|
54
|
+
* 单文件参与检索的上限(KB)。
|
|
55
55
|
*
|
|
56
|
-
*
|
|
57
|
-
*
|
|
56
|
+
* **必须与 `index.js` 的 `MAX_BODY_BYTES`(256 KB)一致** —— 下面那句真话要如实
|
|
57
|
+
* 说出边界,而这个边界归宿主所有。这是 10.4「镜像表」里的一项(v0.20 之前这里
|
|
58
|
+
* 镜像的是 `HAYSTACK_CHARS = 2500`)。
|
|
58
59
|
*/
|
|
59
|
-
const
|
|
60
|
+
const MAX_INDEXED_KB = 256
|
|
60
61
|
|
|
61
62
|
/**
|
|
62
63
|
* 「工作区里有文档,但当前话题一个词都没命中」时补的那句真话。
|
|
63
64
|
*
|
|
64
|
-
*
|
|
65
|
-
*
|
|
65
|
+
* ⚠️ v0.20 改写了这句话。v0.19 及以前它说的是「只在每篇前 2500 字里找,更深的
|
|
66
|
+
* 用 grep」—— 那是当时评分窗口的真实限制。v0.20 取消了这个窗口(需求 §3),
|
|
67
|
+
* 那句话**从今往后是假的**,留着还会让模型为一件不存在的事去做多余的 `grep`。
|
|
68
|
+
*
|
|
69
|
+
* 现在真正的边界只剩两条,都要如实说出来:单文件大小上限(`MAX_INDEXED_KB`)
|
|
70
|
+
* 与媒体没有正文(需求 §17)。
|
|
66
71
|
*/
|
|
67
|
-
const
|
|
68
|
-
`
|
|
72
|
+
const FULLTEXT_NOTE =
|
|
73
|
+
`Every document and code file was searched in full (files over ${MAX_INDEXED_KB} KB are `
|
|
74
|
+
+ 'indexed only up to that size); images and videos have no searchable text.'
|
|
69
75
|
|
|
70
76
|
/**
|
|
71
77
|
* 模型面向的描述。**必须短** —— 它会进每一次请求的系统提示词。
|
|
@@ -86,10 +92,11 @@ const HAYSTACK_NOTE =
|
|
|
86
92
|
* 与**不依赖文件名**。最后一句是行为引导 —— 直说「别自己来」。
|
|
87
93
|
*/
|
|
88
94
|
const DESCRIPTION = 'Project context for the current task, from the workspace documents and code: '
|
|
89
|
-
+ 'primary (read first) / supporting (evidence, implementation) / related
|
|
90
|
-
+ '
|
|
91
|
-
+ 'by
|
|
92
|
-
+ '
|
|
95
|
+
+ 'primary (read first) / supporting (evidence, implementation) / related, each with its '
|
|
96
|
+
+ 'matched passages (line range + snippet). '
|
|
97
|
+
+ 'Ranked by IDF-weighted relevance (or explicit query), then split '
|
|
98
|
+
+ 'by deterministic rules — prefer it to globbing or counting keyword hits. '
|
|
99
|
+
+ 'Reads the workspace; stores nothing, calls no model.'
|
|
93
100
|
|
|
94
101
|
/**
|
|
95
102
|
* 参数 schema。与 `defineTool` 的编译产物逐字一致
|
|
@@ -173,6 +180,32 @@ const ITEM_SCHEMA = {
|
|
|
173
180
|
// 时间序模式没有命中词,抽不出来就不带这个字段,
|
|
174
181
|
// 而不是给个空串假装有。
|
|
175
182
|
snippet: { type: 'string' },
|
|
183
|
+
// v0.20:命中**内容片段**(需求 §11)。文件仍是这个工具的基本实体,
|
|
184
|
+
// `matches` 是附加在它上面的一层:最多 `PASSAGE_MAX_PER_FILE`(2)段,
|
|
185
|
+
// 按行号升序,每段自带行号与偏移量 —— 拿到它就能直接去读那一小段,
|
|
186
|
+
// 不必把整篇大文件塞进上下文(需求 §15/§16)。
|
|
187
|
+
// **可选**:没有片段(零命中、媒体、窗口外、`bodyTf` 不足)时这个键不出现,
|
|
188
|
+
// 而不是给个空数组假装搜过。
|
|
189
|
+
matches: {
|
|
190
|
+
type: 'array',
|
|
191
|
+
items: {
|
|
192
|
+
type: 'object',
|
|
193
|
+
additionalProperties: false,
|
|
194
|
+
properties: {
|
|
195
|
+
// 1-based,闭区间 —— 与编辑器里看到的一致。
|
|
196
|
+
startLine: { type: 'integer' },
|
|
197
|
+
endLine: { type: 'integer' },
|
|
198
|
+
// 0-based 字符偏移,`text.slice(startOffset, endOffset)` 恒等于这段原文。
|
|
199
|
+
startOffset: { type: 'integer' },
|
|
200
|
+
endOffset: { type: 'integer' },
|
|
201
|
+
// 这一段里真实命中的话题词(来自 `rankByRelevance` 的 `matchedTerms`)。
|
|
202
|
+
terms: { type: 'array', items: { type: 'string' } },
|
|
203
|
+
// 这一段里**最相关**的那 200 字(不是整段)。
|
|
204
|
+
snippet: { type: 'string' },
|
|
205
|
+
},
|
|
206
|
+
required: ['startLine', 'endLine', 'startOffset', 'endOffset', 'terms', 'snippet'],
|
|
207
|
+
},
|
|
208
|
+
},
|
|
176
209
|
},
|
|
177
210
|
// `kind` 也是 required:`buildContext()` 每条都给了(取不到时回落 `'md'`)。
|
|
178
211
|
// 声明成可选就等于允许「有的条目有 kind、有的没有」这种形状漂移。
|
|
@@ -298,7 +331,10 @@ function oneLine(text) {
|
|
|
298
331
|
* 1. **在原文上切,不在 `haystack` 上切。** `haystack.body` 是 `.toLowerCase()` 过的
|
|
299
332
|
* (`index.js:240`),在它上面切会把 `BM25` 变成 `bm25` ——
|
|
300
333
|
* 与「标签是你自己打的字,大小写原样保留」这条既有承诺直接冲突。
|
|
301
|
-
* 2.
|
|
334
|
+
* 2. **全文分块**(v0.20)。以前只看每篇前 2500 字,是为了与评分窗口对齐
|
|
335
|
+
* (否则会出现「排上来但段落里没命中词」)。窗口取消后评分看全文,这里也看全文 ——
|
|
336
|
+
* 不过正常路径上命中片段已由 `passage.js` 在评分时算好(`doc.matches`),
|
|
337
|
+
* 这个函数现在是「没有片段数据时的兜底」。
|
|
302
338
|
* 3. **块太长时以命中词为中心截**,不是从头截 —— 否则命中那句话可能正好被截掉,
|
|
303
339
|
* 段落就白给了。
|
|
304
340
|
* 4. **跳过与标题重复的块。** 拿真实工作区试跑时发现的:一篇文档的 H1 标题里含全部命中词,
|
|
@@ -324,10 +360,8 @@ export function pickSnippet(text, terms, options = {}) {
|
|
|
324
360
|
const norm = (s) => String(s).replace(/[#*|`>\s]+/g, ' ').trim().toLowerCase()
|
|
325
361
|
const titleNorm = norm(options.title || '')
|
|
326
362
|
|
|
327
|
-
const window = source.slice(0, SNIPPET_WINDOW)
|
|
328
|
-
|
|
329
363
|
// 按空行切块 —— 纯字符串运算,不解析 Markdown 结构
|
|
330
|
-
const blocks =
|
|
364
|
+
const blocks = source.split(/\n\s*\n/).map((block) => block.trim()).filter(Boolean)
|
|
331
365
|
if (blocks.length === 0) return ''
|
|
332
366
|
|
|
333
367
|
// 选**命中词种数最多**的那块;并列取靠前的(不给后面的块不该有的优势)
|
|
@@ -419,21 +453,52 @@ export function renderToolText(value, readSnippet) {
|
|
|
419
453
|
if (total === 0) return EMPTY
|
|
420
454
|
// 文档在、但一个词都没命中 —— **不许说成「工作区里没有文档」**:
|
|
421
455
|
// 那是一句假话,而且会把 agent 推向一个错的结论(「这个项目里没有相关材料」)。
|
|
422
|
-
//
|
|
423
|
-
//
|
|
424
|
-
//
|
|
456
|
+
// 真机实测(v0.19 的时代):问「路径越界怎么防」时 49 篇一篇都没命中,因为文档侧
|
|
457
|
+
// 只看每篇**前 2500 字**,而这个词在 5 篇 .md 里全部出现在 2500 字之后。
|
|
458
|
+
// **v0.20 取消了这个窗口**,所以「0 命中」现在是句更强的话;
|
|
459
|
+
// 但仍要把真实边界(单文件大小上限、媒体无正文)说出来,见 `FULLTEXT_NOTE`。
|
|
425
460
|
return [
|
|
426
461
|
`No document or code file matched the current topic — 0 of ${files(total)} contain the query terms.`,
|
|
427
|
-
|
|
462
|
+
FULLTEXT_NOTE,
|
|
428
463
|
].join('\n')
|
|
429
464
|
}
|
|
430
465
|
|
|
431
|
-
/**
|
|
466
|
+
/**
|
|
467
|
+
* 一项的命中片段(v0.20)。
|
|
468
|
+
*
|
|
469
|
+
* 正常路径上片段是 `passage.js` 在评分时算好的(`item.matches`,带行号);
|
|
470
|
+
* `readSnippet` 是不带片段数据时的兜底(老调用方、窗口外的文档)。
|
|
471
|
+
* 两者都没有就不渲染 `match:` 那一行 —— 不编造。
|
|
472
|
+
*
|
|
473
|
+
* 行号只在 `matches` 存在时才有,所以旧的 `readSnippet` 返回值一字不改。
|
|
474
|
+
*/
|
|
475
|
+
const matchLine = (item) => {
|
|
476
|
+
const matches = item && Array.isArray(item.matches) ? item.matches : []
|
|
477
|
+
const first = matches.find((m) => m && typeof m.snippet === 'string' && m.snippet)
|
|
478
|
+
if (first) {
|
|
479
|
+
const range = Number.isInteger(first.startLine) && Number.isInteger(first.endLine)
|
|
480
|
+
? `lines ${first.startLine}–${first.endLine} — ` : ''
|
|
481
|
+
return `${range}${flatten(first.snippet, SNIPPET_CHARS)}`
|
|
482
|
+
}
|
|
483
|
+
const raw = typeof readSnippet === 'function' ? readSnippet(item) : ''
|
|
484
|
+
return raw ? flatten(raw, SNIPPET_CHARS) : ''
|
|
485
|
+
}
|
|
486
|
+
|
|
487
|
+
/**
|
|
488
|
+
* **只渲染一段**(`match:`)。第二段(`also:`)在 v0.20 实测后被砍掉 ——
|
|
489
|
+
* 保留这段注释,免得下一个人又把它加回来。
|
|
490
|
+
*
|
|
491
|
+
* 需求 §16 的预算是「工具输出不得因为片段而膨胀」。实测(30 篇全命中的压力
|
|
492
|
+
* 语料、5 条结果、比较渲染后的文本而不是结构化 value):v0.19 基线 2702 字符,
|
|
493
|
+
* 带 `match:` + `also:` 两段时 4614 字符 = **1.71×**,超过实现说明 §7 R2 定的
|
|
494
|
+
* 1.4× ⇒ 按那条规则把**工具侧**降到一段(砍后 1.35×)。面板侧仍是每文件 ≤2 段:
|
|
495
|
+
* 它走本地 HTTP、不进模型上下文,需求 §11 的「可带多段」在那里成立。
|
|
496
|
+
* 这也正对需求 §15 的措辞:给的是「**最相关片段**」(单数)+ 文件 + 理由。
|
|
497
|
+
*/
|
|
432
498
|
const lines = (items) => items.map((item, index) => {
|
|
433
499
|
const summary = oneLine(item.summary)
|
|
434
500
|
const why = whyText(item.reason)
|
|
435
|
-
const
|
|
436
|
-
const snippet = raw ? flatten(raw, SNIPPET_CHARS) : ''
|
|
501
|
+
const snippet = matchLine(item)
|
|
437
502
|
return `${index + 1}. ${item.rel} — ${item.title}`
|
|
438
503
|
+ `${summary ? `\n ${summary}` : ''}`
|
|
439
504
|
+ `${why ? `\n Why: ${why}` : ''}`
|
|
@@ -658,9 +723,25 @@ export function knitDocsDefinition(scan, read, contextFor, audit) {
|
|
|
658
723
|
mtimeMs: Number.isFinite(item.mtimeMs) ? Math.trunc(item.mtimeMs) : 0,
|
|
659
724
|
})
|
|
660
725
|
|
|
726
|
+
// v0.20:命中片段**在 `scan()` 里就算好了**(`payload.ranked[].matches`,带行号),
|
|
727
|
+
// 键是 `rel`。有片段就不再读盘 —— 这是顺带拿到的性能收益:v0.19 为了抽 200 字,
|
|
728
|
+
// 每一条都要把整篇文件再读一遍(`readDocument` → `pickSnippet`)。
|
|
729
|
+
const matchesByRel = new Map()
|
|
730
|
+
for (const doc of (Array.isArray(payload.ranked) ? payload.ranked : [])) {
|
|
731
|
+
if (Array.isArray(doc.matches) && doc.matches.length > 0) {
|
|
732
|
+
matchesByRel.set(String(doc.rel || ''), doc.matches)
|
|
733
|
+
}
|
|
734
|
+
}
|
|
735
|
+
|
|
661
736
|
// 逐个抽命中段落 —— **只对真正要返回的条目做 I/O**,不在全量名次上读盘。
|
|
662
737
|
const withSnippets = async (items) => Promise.all(items.map(async (raw) => {
|
|
663
738
|
const item = project(raw)
|
|
739
|
+
const matches = matchesByRel.get(String(item.rel || ''))
|
|
740
|
+
if (matches) {
|
|
741
|
+
// 单段也照旧填 `snippet` —— 渲染与老调用方都只认它。
|
|
742
|
+
const first = matches.find((m) => m && typeof m.snippet === 'string' && m.snippet)
|
|
743
|
+
return first ? { ...item, matches, snippet: first.snippet } : { ...item, matches }
|
|
744
|
+
}
|
|
664
745
|
const snippet = await snippetOf(item)
|
|
665
746
|
return snippet ? { ...item, snippet } : item
|
|
666
747
|
}))
|