dsh-knit 0.17.0 → 0.19.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 +333 -2
- package/README.en.md +128 -31
- package/README.md +142 -25
- package/SECURITY.md +4 -3
- package/package.json +6 -4
- package/src/client/client.js +1146 -194
- package/src/host/classification.js +250 -0
- package/src/host/context.js +31 -9
- package/src/host/index.js +336 -77
- package/src/host/tool.js +29 -13
- package/test/classification.test.mjs +237 -0
- package/test/client.test.mjs +982 -54
- package/test/code-context.test.mjs +567 -0
- package/test/eval/fixture.mjs +309 -6
- package/test/eval.test.mjs +117 -1
- package/test/harness.mjs +4 -1
- package/test/host.test.mjs +63 -3
- package/test/i18n.test.mjs +188 -5
- package/test/path.test.mjs +97 -5
- package/test/tool.test.mjs +23 -15
package/src/host/index.js
CHANGED
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
* 零模型、零网络出口:只读本地文件与会话日志。
|
|
15
15
|
*/
|
|
16
16
|
import { readFile, readdir, stat } from 'node:fs/promises'
|
|
17
|
-
import { createReadStream, statSync } from 'node:fs'
|
|
17
|
+
import { createReadStream, realpathSync, statSync } from 'node:fs'
|
|
18
18
|
import { join, relative, resolve, sep } from 'node:path'
|
|
19
19
|
import { homedir } from 'node:os'
|
|
20
20
|
import { extractKeywords, rankByRelevance, topicLabel } from './relevance.js'
|
|
@@ -26,6 +26,13 @@ import { buildLinkGraph, linksOf } from './links.js'
|
|
|
26
26
|
// `renderToolText()` 里发生(模型看到的是那段文本,不是结构化 JSON)。曾经多导出一个
|
|
27
27
|
// `renderContextText` 却没人调用 —— 那是个会与 `tool.js` 漂移的第二渲染器,已删。
|
|
28
28
|
import { buildContext } from './context.js'
|
|
29
|
+
// v0.19:文件分类层。**所有「这个文件是什么、能不能预览/检索/进上下文」的判断都在这里**,
|
|
30
|
+
// 本文件(以及 retrieval / preview / UI)不再自己看扩展名 —— 见 `classification.js` 的文件头。
|
|
31
|
+
import {
|
|
32
|
+
classifyFile, isContextKind, isPreviewKind,
|
|
33
|
+
KIND_DOCUMENT, KIND_CODE, KIND_IMAGE, KIND_VIDEO, KIND_GENERATED, KIND_IGNORED,
|
|
34
|
+
IMAGE_TYPES, VIDEO_TYPES,
|
|
35
|
+
} from './classification.js'
|
|
29
36
|
// v0.15:Context Feedback / Context Audit —— 「Context Pack 之后真的被用了吗」。
|
|
30
37
|
// ⚠️ 只做三件确定性的事:从会话事件里抽**真实的 `read`**、把交出去的包记成 Snapshot、
|
|
31
38
|
// 把两者接起来算 Usage。**不订阅 event bus、不落盘、不联网、不调模型、不改 Retrieval。**
|
|
@@ -45,8 +52,30 @@ const MAX_DIRS = 500
|
|
|
45
52
|
const MAX_DOCS = 400
|
|
46
53
|
/** 图片/视频等媒体产物的扫描上限(与文档分开计数,避免截图刷爆文档列表)。 */
|
|
47
54
|
const MAX_MEDIA = 400
|
|
55
|
+
/**
|
|
56
|
+
* 代码产物的扫描上限(v0.19)。
|
|
57
|
+
*
|
|
58
|
+
* ⚠️ 这个数字是**审计真实工作区之后定的**,不是拍的:
|
|
59
|
+
* 拿 `DeepSeek Harness Native` 这一级真实工作区数过一遍,根下有 635 篇 Markdown、
|
|
60
|
+
* 773 个代码文件(`.mjs` 270 / `.js` 173 / `.json` 122 / `.py` 105 / `.html` 74 /
|
|
61
|
+
* `.yml` 13 / `.css` 10 / `.sh` 5),代码比文档多约 1.2 倍。
|
|
62
|
+
*
|
|
63
|
+
* 所以取 **300**(≈ 0.75 × `MAX_DOCS`)而不是和文档齐平 400:
|
|
64
|
+
* 「支持代码」不该让代码把原有的 Markdown 上下文挤出去(需求 §15),
|
|
65
|
+
* 同一批语料里代码的准入名额略小于文档,是这条要求最直接的落实。
|
|
66
|
+
* 另外它在面板里也不与文档竞争 —— 文档档的语料只有 Markdown(见 `scan()`)。
|
|
67
|
+
*/
|
|
68
|
+
const MAX_CODE = 300
|
|
48
69
|
const SCAN_BUDGET_MS = 4000
|
|
49
70
|
const HEAD_BYTES = 16 * 1024
|
|
71
|
+
/**
|
|
72
|
+
* 代码文件参与扫描时读取的头部字节数(v0.19)。
|
|
73
|
+
*
|
|
74
|
+
* 比 Markdown 的 16KB 更小是**刻意的**:代码的 haystack 只需要前 `HAYSTACK_CHARS`
|
|
75
|
+
* 个字符,而真实项目里 `.ts` / `.js` 的数量可能非常高 —— 这是「bounded content read」
|
|
76
|
+
* 那条要求(需求 §16)唯一的落地点。
|
|
77
|
+
*/
|
|
78
|
+
const CODE_HEAD_BYTES = 8 * 1024
|
|
50
79
|
/** 单次内联预览返回的正文上限(超出截断,面板只做预览不做全量阅读)。 */
|
|
51
80
|
const DOC_MAX_BYTES = 512 * 1024
|
|
52
81
|
/** 参与相关性打分的正文长度(不需要整篇)。 */
|
|
@@ -79,34 +108,9 @@ const TASK_ACK = new Set([
|
|
|
79
108
|
])
|
|
80
109
|
|
|
81
110
|
/**
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
* `/knit/api/raw` 是按路径读文件的接口,口子必须收窄:只有在这个表里的扩展名才放行,
|
|
85
|
-
* 否则就成了「能读工作区里任意文件」的后门。
|
|
86
|
-
*/
|
|
87
|
-
const IMAGE_TYPES = new Map([
|
|
88
|
-
['png', 'image/png'],
|
|
89
|
-
['jpg', 'image/jpeg'],
|
|
90
|
-
['jpeg', 'image/jpeg'],
|
|
91
|
-
['gif', 'image/gif'],
|
|
92
|
-
['webp', 'image/webp'],
|
|
93
|
-
['avif', 'image/avif'],
|
|
94
|
-
['bmp', 'image/bmp'],
|
|
95
|
-
['ico', 'image/x-icon'],
|
|
96
|
-
['svg', 'image/svg+xml'],
|
|
97
|
-
])
|
|
98
|
-
|
|
99
|
-
/**
|
|
100
|
-
* 允许内联渲染的视频类型白名单。
|
|
101
|
-
* 与 IMAGE_TYPES 同样的口径:只放行表里的扩展名,/raw 不读其它任何文件。
|
|
111
|
+
* 图片/视频的类型白名单已经搬进 `classification.js`(v0.19)—— 扩展名归哪一类
|
|
112
|
+
* 只该有一个事实来源,本文件只 import 它的 MIME 表(`mediaInfo` 按扩展名取 MIME)。
|
|
102
113
|
*/
|
|
103
|
-
const VIDEO_TYPES = new Map([
|
|
104
|
-
['mp4', 'video/mp4'],
|
|
105
|
-
['m4v', 'video/mp4'],
|
|
106
|
-
['webm', 'video/webm'],
|
|
107
|
-
['mov', 'video/quicktime'],
|
|
108
|
-
['ogv', 'video/ogg'],
|
|
109
|
-
])
|
|
110
114
|
|
|
111
115
|
/** 单张内联图片的字节上限。 */
|
|
112
116
|
const MAX_IMAGE_BYTES = 12 * 1024 * 1024
|
|
@@ -117,10 +121,13 @@ const MAX_IMAGE_BYTES = 12 * 1024 * 1024
|
|
|
117
121
|
*/
|
|
118
122
|
const MAX_VIDEO_BYTES = 256 * 1024 * 1024
|
|
119
123
|
|
|
120
|
-
/**
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
+
/**
|
|
125
|
+
* 列表条目类型:文档(Markdown)/ 代码 / 图片 / 视频。
|
|
126
|
+
*
|
|
127
|
+
* v0.19 起这四个常量由 `classification.js` 拥有并在这里重新导出(`KIND_*` 是本文件的
|
|
128
|
+
* 惯用名)。**不要再在本文件里写扩展名判断** —— 那正是要收拢的东西。
|
|
129
|
+
*/
|
|
130
|
+
const KIND_DOC = KIND_DOCUMENT
|
|
124
131
|
|
|
125
132
|
/**
|
|
126
133
|
* 机器可读的错误码。
|
|
@@ -130,7 +137,15 @@ const KIND_VIDEO = 'video'
|
|
|
130
137
|
*/
|
|
131
138
|
export const ERROR_CODES = {
|
|
132
139
|
outsideWorkspace: 'knit/outside-workspace',
|
|
133
|
-
|
|
140
|
+
/**
|
|
141
|
+
* v0.19:从 `knit/markdown-only` 改名。
|
|
142
|
+
*
|
|
143
|
+
* 名字必须跟着能力改 —— 这个码现在表示「这个类型不支持在面板里预览」
|
|
144
|
+
* (媒体、二进制、这一版不支持的代码语言、未知扩展名),
|
|
145
|
+
* 而不只是「不是 Markdown」。留着旧名字会让下一个读代码的人以为
|
|
146
|
+
* 放行范围还是「只有 Markdown」。
|
|
147
|
+
*/
|
|
148
|
+
notPreviewable: 'knit/not-previewable',
|
|
134
149
|
notFound: 'knit/not-found',
|
|
135
150
|
notAFile: 'knit/not-a-file',
|
|
136
151
|
imageOnly: 'knit/image-only',
|
|
@@ -282,41 +297,111 @@ async function readDoc(absPath) {
|
|
|
282
297
|
}
|
|
283
298
|
|
|
284
299
|
/**
|
|
285
|
-
*
|
|
286
|
-
*
|
|
287
|
-
*
|
|
300
|
+
* 读一个**代码文件**参与检索所需的头部(v0.19),命中缓存则跳过读盘。
|
|
301
|
+
*
|
|
302
|
+
* 与 `readDoc` 共用同一张 `cache`(键是绝对路径,一个路径只可能是文档或代码之一),
|
|
303
|
+
* 并复用同一套 `haystack` 形状 —— 这正是「不给代码建第二套检索」在数据层面的落实:
|
|
304
|
+
* `relevance.js` 一个字节都不用改,它看到的仍是它一直在看的 `{title, summary, body}`。
|
|
305
|
+
*
|
|
306
|
+
* haystack 的字段语义在这里被**重新指派**(需求 §13:代码不复用 Markdown 的语义):
|
|
307
|
+
*
|
|
308
|
+
* - `title` ← 文件名(权重 4,最高价值字段:`plugin-loader.js` 本身就带任务语义)
|
|
309
|
+
* - `summary` ← 工作区相对路径的目录部分(权重 2)
|
|
310
|
+
* - `body` ← 正文前 `HAYSTACK_CHARS` 个字符(权重 1)
|
|
311
|
+
*
|
|
312
|
+
* 于是 `FIELD_WEIGHTS` 现成的 4 / 2 / 1 恰好等于
|
|
313
|
+
* 「filename × 4 / path × 2 / content × 1」,排序器零改动。
|
|
314
|
+
*
|
|
315
|
+
* @param {string} absPath - 绝对路径
|
|
316
|
+
* @param {string} root - 工作区根
|
|
317
|
+
* @returns {Promise<object|null>} 解析结果,读失败返回 null
|
|
288
318
|
*/
|
|
289
|
-
function
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
319
|
+
async function readCode(absPath, root) {
|
|
320
|
+
let st
|
|
321
|
+
try {
|
|
322
|
+
st = await stat(absPath)
|
|
323
|
+
} catch {
|
|
324
|
+
return null
|
|
325
|
+
}
|
|
326
|
+
if (!st.isFile()) return null
|
|
327
|
+
|
|
328
|
+
const hit = cache.get(absPath)
|
|
329
|
+
if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size) return hit
|
|
330
|
+
|
|
331
|
+
let head = ''
|
|
332
|
+
try {
|
|
333
|
+
const buf = await readFile(absPath)
|
|
334
|
+
head = buf.subarray(0, CODE_HEAD_BYTES).toString('utf8')
|
|
335
|
+
} catch {
|
|
336
|
+
return null
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
const name = absPath.split(sep).pop() || absPath
|
|
340
|
+
const rel = relative(root, absPath).split(sep).join('/')
|
|
341
|
+
const cut = rel.lastIndexOf('/')
|
|
342
|
+
// 目录部分保留结尾的 `/`(`src/context/`),与列表里第二行的观感一致;
|
|
343
|
+
// 根目录下的文件是空串 —— 不编一个 `/` 出来。
|
|
344
|
+
const dir = cut >= 0 ? rel.slice(0, cut + 1) : ''
|
|
345
|
+
|
|
346
|
+
const entry = {
|
|
347
|
+
mtimeMs: st.mtimeMs,
|
|
348
|
+
size: st.size,
|
|
349
|
+
head,
|
|
350
|
+
// ⚠️ 标题是**带扩展名的文件名**,不是去扩展名的 stem。
|
|
351
|
+
// 代码的文件名里扩展名是信息的一部分(`plugin-loader.js` vs `plugin.json`),
|
|
352
|
+
// 去掉它反而丢掉了最能区分两个候选的那个字符。
|
|
353
|
+
title: name,
|
|
354
|
+
// 摘要位放路径。列表第二行本来就在显示路径,这里只是让同一个值也能参与打分。
|
|
355
|
+
summary: dir,
|
|
356
|
+
hayTitle: name.toLowerCase(),
|
|
357
|
+
haySummary: dir.toLowerCase(),
|
|
358
|
+
hayBody: head.slice(0, HAYSTACK_CHARS).toLowerCase(),
|
|
359
|
+
}
|
|
360
|
+
cache.set(absPath, entry)
|
|
361
|
+
return entry
|
|
295
362
|
}
|
|
296
363
|
|
|
297
364
|
/**
|
|
298
|
-
*
|
|
365
|
+
* 广度优先扫出工作区里的文档、代码与媒体文件(v0.19)。
|
|
366
|
+
*
|
|
367
|
+
* 一次遍历同时收三类,目录预算与时间预算共享;三类各自有数量上限,
|
|
368
|
+
* 截图再多也不会把文档名额挤光,代码再多也不会(见 `MAX_CODE`)。
|
|
299
369
|
*
|
|
300
|
-
*
|
|
301
|
-
*
|
|
370
|
+
* **扫描只做「目录元数据 → 分类 → 准入」**:这里不读任何文件内容,
|
|
371
|
+
* 正文读取留给 `collectDocs`(bounded,见 `readCode`)。
|
|
302
372
|
*
|
|
303
373
|
* @param {string} root - 工作区根(会话 cwd)
|
|
304
|
-
* @returns {Promise<{md: string[], media: Array<{abs:string, kind:string}>,
|
|
305
|
-
* mdTruncated: boolean, mediaTruncated: boolean
|
|
374
|
+
* @returns {Promise<{md: string[], code: string[], media: Array<{abs:string, kind:string}>,
|
|
375
|
+
* mdTruncated: boolean, codeTruncated: boolean, mediaTruncated: boolean,
|
|
376
|
+
* stats: object, scanMs: number}>} 分类后的绝对路径与计数
|
|
306
377
|
*/
|
|
307
378
|
async function collectEntries(root) {
|
|
379
|
+
const startedAt = Date.now()
|
|
308
380
|
/** @type {string[]} */
|
|
309
381
|
const md = []
|
|
382
|
+
/** @type {string[]} */
|
|
383
|
+
const code = []
|
|
310
384
|
/** @type {Array<{abs:string, kind:string}>} */
|
|
311
385
|
const media = []
|
|
312
|
-
const deadline =
|
|
386
|
+
const deadline = startedAt + SCAN_BUDGET_MS
|
|
313
387
|
/** @type {Array<{dir:string,depth:number}>} */
|
|
314
388
|
const queue = [{ dir: root, depth: 0 }]
|
|
315
389
|
let visited = 0
|
|
390
|
+
/**
|
|
391
|
+
* v0.19 验收要的计数(需求 §50)。
|
|
392
|
+
* `codeSeen` 是**见到的**代码文件数,`codeAdmitted` 是进语料的,
|
|
393
|
+
* `codeExcluded` 是被 `MAX_CODE` 挡在外面的 —— 三者分开,才看得出上限有没有真的生效。
|
|
394
|
+
*/
|
|
395
|
+
const stats = {
|
|
396
|
+
mdSeen: 0, mdAdmitted: 0,
|
|
397
|
+
codeSeen: 0, codeAdmitted: 0, codeExcluded: 0,
|
|
398
|
+
mediaSeen: 0, mediaAdmitted: 0,
|
|
399
|
+
generated: 0, ignored: 0,
|
|
400
|
+
}
|
|
316
401
|
|
|
317
402
|
while (queue.length > 0) {
|
|
318
403
|
if (visited >= MAX_DIRS
|
|
319
|
-
|| (md.length >= MAX_DOCS && media.length >= MAX_MEDIA)
|
|
404
|
+
|| (md.length >= MAX_DOCS && media.length >= MAX_MEDIA && code.length >= MAX_CODE)
|
|
320
405
|
|| Date.now() > deadline) break
|
|
321
406
|
const { dir, depth } = queue.shift()
|
|
322
407
|
visited += 1
|
|
@@ -336,11 +421,26 @@ async function collectEntries(root) {
|
|
|
336
421
|
if (entry.name.startsWith('.')) continue
|
|
337
422
|
queue.push({ dir: abs, depth: depth + 1 })
|
|
338
423
|
} else if (entry.isFile()) {
|
|
339
|
-
const
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
424
|
+
const info = classifyFile(entry.name)
|
|
425
|
+
// **准入判定只有这一处**:`isContextKind()` 回答「算不算上下文候选」,
|
|
426
|
+
// 下面再按具体类型分账。配额与计数必须分开 —— v0.19 的 corpus pressure
|
|
427
|
+
// 要求能看出到底是文档还是代码把语料撑大的(需求 §15 §50)。
|
|
428
|
+
if (isContextKind(info.kind)) {
|
|
429
|
+
if (info.kind === KIND_DOC) {
|
|
430
|
+
stats.mdSeen += 1
|
|
431
|
+
if (md.length < MAX_DOCS) { md.push(abs); stats.mdAdmitted += 1 }
|
|
432
|
+
} else {
|
|
433
|
+
stats.codeSeen += 1
|
|
434
|
+
if (code.length < MAX_CODE) { code.push(abs); stats.codeAdmitted += 1 } else stats.codeExcluded += 1
|
|
435
|
+
}
|
|
436
|
+
} else if (info.kind === KIND_IMAGE || info.kind === KIND_VIDEO) {
|
|
437
|
+
stats.mediaSeen += 1
|
|
438
|
+
if (media.length < MAX_MEDIA) { media.push({ abs, kind: info.kind }); stats.mediaAdmitted += 1 }
|
|
439
|
+
} else if (info.kind === KIND_GENERATED) {
|
|
440
|
+
// 生成/噪声产物:**数一下,但一个都不准入**(需求 §6 §7)。
|
|
441
|
+
stats.generated += 1
|
|
442
|
+
} else {
|
|
443
|
+
stats.ignored += 1
|
|
344
444
|
}
|
|
345
445
|
}
|
|
346
446
|
}
|
|
@@ -348,9 +448,13 @@ async function collectEntries(root) {
|
|
|
348
448
|
|
|
349
449
|
return {
|
|
350
450
|
md,
|
|
451
|
+
code,
|
|
351
452
|
media,
|
|
352
453
|
mdTruncated: md.length >= MAX_DOCS,
|
|
454
|
+
codeTruncated: code.length >= MAX_CODE,
|
|
353
455
|
mediaTruncated: media.length >= MAX_MEDIA,
|
|
456
|
+
stats,
|
|
457
|
+
scanMs: Date.now() - startedAt,
|
|
354
458
|
}
|
|
355
459
|
}
|
|
356
460
|
|
|
@@ -386,10 +490,15 @@ async function readMediaMeta(root, { abs, kind }) {
|
|
|
386
490
|
}
|
|
387
491
|
|
|
388
492
|
/**
|
|
389
|
-
*
|
|
493
|
+
* 扫出工作区里全部文档、代码与媒体的元信息(各自按 mtime 倒序)。
|
|
494
|
+
*
|
|
495
|
+
* 三类共用一次目录遍历(`collectEntries`),但**只有文档与代码会读正文头部**
|
|
496
|
+
* ——媒体永远只 stat(视频可能上百 MB)。
|
|
497
|
+
*
|
|
390
498
|
* @param {string} root - 工作区根
|
|
391
|
-
* @returns {Promise<{docs: Array<object>, media: Array<object>,
|
|
392
|
-
* truncated: boolean, mediaTruncated: boolean
|
|
499
|
+
* @returns {Promise<{docs: Array<object>, code: Array<object>, media: Array<object>,
|
|
500
|
+
* truncated: boolean, codeTruncated: boolean, mediaTruncated: boolean,
|
|
501
|
+
* stats: object, scanMs: number}>}
|
|
393
502
|
*/
|
|
394
503
|
export async function collectDocs(root) {
|
|
395
504
|
const found = await collectEntries(root)
|
|
@@ -414,6 +523,28 @@ export async function collectDocs(root) {
|
|
|
414
523
|
}
|
|
415
524
|
docs.sort((a, b) => b.mtimeMs - a.mtimeMs)
|
|
416
525
|
|
|
526
|
+
// v0.19:代码条目与文档条目**形状完全一致**(同一个 `kind` 位、同一套 haystack、
|
|
527
|
+
// 同一批下游消费者)。差别只在 haystack 字段的语义 —— 见 `readCode`。
|
|
528
|
+
// 这不是「第二套数据模型」,就是同一套模型里多了一类 kind。
|
|
529
|
+
const code = []
|
|
530
|
+
for (const abs of found.code) {
|
|
531
|
+
const meta = await readCode(abs, root)
|
|
532
|
+
if (!meta) continue
|
|
533
|
+
code.push({
|
|
534
|
+
kind: KIND_CODE,
|
|
535
|
+
path: abs,
|
|
536
|
+
rel: relative(root, abs).split(sep).join('/'),
|
|
537
|
+
name: abs.split(sep).pop(),
|
|
538
|
+
title: meta.title,
|
|
539
|
+
summary: meta.summary,
|
|
540
|
+
size: meta.size,
|
|
541
|
+
mtimeMs: meta.mtimeMs,
|
|
542
|
+
head: meta.head,
|
|
543
|
+
haystack: { title: meta.hayTitle, summary: meta.haySummary, body: meta.hayBody },
|
|
544
|
+
})
|
|
545
|
+
}
|
|
546
|
+
code.sort((a, b) => b.mtimeMs - a.mtimeMs)
|
|
547
|
+
|
|
417
548
|
const media = []
|
|
418
549
|
for (const item of found.media) {
|
|
419
550
|
const meta = await readMediaMeta(root, item)
|
|
@@ -421,7 +552,16 @@ export async function collectDocs(root) {
|
|
|
421
552
|
}
|
|
422
553
|
media.sort((a, b) => b.mtimeMs - a.mtimeMs)
|
|
423
554
|
|
|
424
|
-
return {
|
|
555
|
+
return {
|
|
556
|
+
docs,
|
|
557
|
+
code,
|
|
558
|
+
media,
|
|
559
|
+
truncated: found.mdTruncated,
|
|
560
|
+
codeTruncated: found.codeTruncated,
|
|
561
|
+
mediaTruncated: found.mediaTruncated,
|
|
562
|
+
stats: found.stats,
|
|
563
|
+
scanMs: found.scanMs,
|
|
564
|
+
}
|
|
425
565
|
}
|
|
426
566
|
|
|
427
567
|
/* ── 会话事件 → 对话文本 ────────────────────────────── */
|
|
@@ -606,18 +746,44 @@ function publicDoc(doc) {
|
|
|
606
746
|
* HTTP 路由必须走 `publicScanPayload()`(`test/host.test.mjs` 有守卫)。
|
|
607
747
|
*/
|
|
608
748
|
export async function scan(root, limit, options = {}) {
|
|
609
|
-
|
|
749
|
+
// v0.19 修订:**扫的是展开符号链接后的那份路径**。
|
|
750
|
+
// 每条记录里的 `path`(`publicDoc()` 原样下发给客户端)就是「打开 / 定位」时
|
|
751
|
+
// 交给宿主的路径,而 DSH 只认 realpath(见 `hostPathOf()`)—— 跟着会话的
|
|
752
|
+
// 符号链接走一遍,客户端拿到的 `path` 直接可用,不必等 `/api/doc` 回来再校正。
|
|
753
|
+
// ⚠️ `rel` 用同一个 base 算,所以相对路径一字不变;对外的 `root` 仍是会话
|
|
754
|
+
// 原本那条(界面显示用),canonical 的那份单独放在 `hostRoot`。
|
|
755
|
+
const hostRoot = hostPathOf(root)
|
|
756
|
+
const collected = await collectDocs(hostRoot)
|
|
610
757
|
|
|
611
758
|
// 默认 doc:旧版客户端 / 悬停浮层不带 kind,行为与「只列 Markdown」时完全一致。
|
|
612
|
-
|
|
759
|
+
//
|
|
760
|
+
// v0.19 的 `kind` 取值集合(**唯一权威**,HTTP 与工具都从这里取):
|
|
761
|
+
// `doc` 仅 Markdown(默认,v0.18 行为逐字不变)
|
|
762
|
+
// `code` 仅代码(v0.19)
|
|
763
|
+
// `media` 仅图片/视频(v0.18 行为逐字不变)
|
|
764
|
+
// `all` 文档 + 代码 + 媒体(面板「全部」档;v0.18 是「文档 + 媒体」,只多不少)
|
|
765
|
+
// `context` **内部**语料:文档 + 代码。不给 HTTP —— agent 工具的 Context Pack
|
|
766
|
+
// 要在「文档与代码混合竞争」上排序(需求 §34 Case C),而媒体不进上下文,
|
|
767
|
+
// 所以它不能复用 `all`(那会把媒体也塞进候选)。
|
|
768
|
+
const kind = options.kind === 'all' || options.kind === 'media'
|
|
769
|
+
|| options.kind === 'code' || options.kind === 'context'
|
|
770
|
+
? options.kind
|
|
771
|
+
: 'doc'
|
|
613
772
|
let pool
|
|
614
773
|
let truncated
|
|
615
774
|
if (kind === 'media') {
|
|
616
775
|
pool = collected.media
|
|
617
776
|
truncated = collected.mediaTruncated
|
|
777
|
+
} else if (kind === 'code') {
|
|
778
|
+
pool = collected.code
|
|
779
|
+
truncated = collected.codeTruncated
|
|
780
|
+
} else if (kind === 'context') {
|
|
781
|
+
pool = collected.docs.concat(collected.code).sort((a, b) => b.mtimeMs - a.mtimeMs)
|
|
782
|
+
truncated = collected.truncated || collected.codeTruncated
|
|
618
783
|
} else if (kind === 'all') {
|
|
619
|
-
pool = collected.docs.concat(collected.
|
|
620
|
-
|
|
784
|
+
pool = collected.docs.concat(collected.code, collected.media)
|
|
785
|
+
.sort((a, b) => b.mtimeMs - a.mtimeMs)
|
|
786
|
+
truncated = collected.truncated || collected.codeTruncated || collected.mediaTruncated
|
|
621
787
|
} else {
|
|
622
788
|
pool = collected.docs
|
|
623
789
|
truncated = collected.truncated
|
|
@@ -666,6 +832,10 @@ export async function scan(root, limit, options = {}) {
|
|
|
666
832
|
return {
|
|
667
833
|
ok: true,
|
|
668
834
|
root,
|
|
835
|
+
// v0.19 修订:`root` 是会话自己那条路径(可能含符号链接,用于显示);
|
|
836
|
+
// `hostRoot` 是同一目录展开链接后的 canonical 路径,**只给「打开 / 定位」用** ——
|
|
837
|
+
// 宿主只认 realpath 形态,理由见 `hostPathOf()`。
|
|
838
|
+
hostRoot,
|
|
669
839
|
kind,
|
|
670
840
|
total: ordered.length,
|
|
671
841
|
truncated,
|
|
@@ -685,6 +855,10 @@ export async function scan(root, limit, options = {}) {
|
|
|
685
855
|
// 全量列表(未按 limit 切片)。**内部输入**:v0.17 的 lifecycle 需要「被读过但
|
|
686
856
|
// 不一定落在当前页」的文档的当前 mtime。由 `publicScanPayload()` 剥掉。
|
|
687
857
|
allDocs: ordered,
|
|
858
|
+
// v0.19 扫描计数(需求 §50 要报的那几个数:见到的 / 准入的 / 被排除的 / 生成噪声)
|
|
859
|
+
// 加上 `corpusSize`(本档语料的实际大小,即 `allDocs.length`)。
|
|
860
|
+
// **内部输入**,由 `publicScanPayload()` 剥掉 —— HTTP 响应形状一个键都不加。
|
|
861
|
+
stats: { ...collected.stats, scanMs: collected.scanMs, corpusSize: ordered.length },
|
|
688
862
|
}
|
|
689
863
|
}
|
|
690
864
|
|
|
@@ -701,10 +875,11 @@ export async function scan(root, limit, options = {}) {
|
|
|
701
875
|
*/
|
|
702
876
|
export function publicScanPayload(payload) {
|
|
703
877
|
if (!payload || typeof payload !== 'object') return payload
|
|
704
|
-
const { ranked, task, allDocs, ...rest } = payload
|
|
878
|
+
const { ranked, task, allDocs, stats, ...rest } = payload
|
|
705
879
|
void ranked
|
|
706
880
|
void task
|
|
707
881
|
void allDocs
|
|
882
|
+
void stats
|
|
708
883
|
return rest
|
|
709
884
|
}
|
|
710
885
|
|
|
@@ -719,16 +894,27 @@ export function publicScanPayload(payload) {
|
|
|
719
894
|
* 同样的 16KB)—— **零额外 I/O**。代价是只看头部 16KB,长文档尾部的引用会漏,
|
|
720
895
|
* 但那只影响「哪些邻居进 Supporting」,不影响任何一篇的名次。
|
|
721
896
|
*
|
|
897
|
+
* v0.19:**入图的一律只看 Markdown**(`buildLinkGraph` 自己也只认 `.md` 目标)。
|
|
898
|
+
* 代码不进图有两个理由,都不是洁癖:
|
|
899
|
+
* 1. 引用图是 `.md` 与 `.md` 之间的关系(`links.js` 的解析规则就是为中文文档语料
|
|
900
|
+
* 量出来的)。把代码的正文塞进这个索引没有语义,只会让 basename 歧义变多。
|
|
901
|
+
* 2. 更重要的是**不能给代码开一条新的入围路径**。代码进 Supporting 的唯一正当理由
|
|
902
|
+
* 应当是「任务检索命中了它」;如果它还能靠「正文里恰好写了一句 `docs/X.md`」
|
|
903
|
+
* 进 Supporting,那就成了「因为它是代码所以特别」的反面 —— 一条不打分的后门。
|
|
904
|
+
*
|
|
722
905
|
* @param {string} root - 工作区根
|
|
723
906
|
* @param {boolean} withLinks - 是否要引用关系
|
|
724
|
-
* @param {Map<string, object>} byRel -
|
|
907
|
+
* @param {Map<string, object>} byRel - 本次扫描到的产物(按 rel)
|
|
725
908
|
* @returns {Promise<object|null>} 图或 null
|
|
726
909
|
*/
|
|
727
910
|
async function linkGraphFor(root, withLinks, byRel) {
|
|
728
911
|
if (!withLinks) return null
|
|
729
912
|
try {
|
|
730
913
|
return await buildLinkGraph(root, {
|
|
731
|
-
list: async () => ({
|
|
914
|
+
list: async () => ({
|
|
915
|
+
docs: [...byRel.values()].filter((doc) => doc.kind === KIND_DOC),
|
|
916
|
+
truncated: false,
|
|
917
|
+
}),
|
|
732
918
|
read: async (_root, rel) => {
|
|
733
919
|
const entry = byRel.get(rel)
|
|
734
920
|
if (!entry || typeof entry.head !== 'string') return { ok: false }
|
|
@@ -801,9 +987,13 @@ function withStats(pack) {
|
|
|
801
987
|
/**
|
|
802
988
|
* 一次请求里的上下文载荷:不适用(时间序 / 媒体档 / 没有命中)时返回 `null`。
|
|
803
989
|
*
|
|
804
|
-
*
|
|
990
|
+
* **只在「文档档 / 代码档 + 相关序」时装配** —— 其余情形返回 null,
|
|
805
991
|
* 客户端于是退回它一直在用的平铺列表,行为与 v0.13 逐字一致。
|
|
806
992
|
*
|
|
993
|
+
* v0.19:代码档走的是**同一个**装配调用,没有任何 code-only 分支。
|
|
994
|
+
* 引用图仍然只有 Markdown 才建(`links.js` 解析的是 Markdown 链接语法,
|
|
995
|
+
* 这是它的既有边界,v0.19 不扩)—— 所以 `withLinks` 只在文档档为真。
|
|
996
|
+
*
|
|
807
997
|
* @param {string} root - 工作区根
|
|
808
998
|
* @param {object} payload - `scan()` 的产物
|
|
809
999
|
* @param {string} sort - 当前排序模式
|
|
@@ -811,7 +1001,8 @@ function withStats(pack) {
|
|
|
811
1001
|
* @returns {Promise<object|null>} Context Pack(带 `summary`)或 null
|
|
812
1002
|
*/
|
|
813
1003
|
async function contextPayload(root, payload, sort, kind) {
|
|
814
|
-
|
|
1004
|
+
const contextKind = kind === 'doc' || kind === 'code' || kind === 'context'
|
|
1005
|
+
if (!payload || payload.mode !== 'relevance' || sort !== 'relevance' || !contextKind) return null
|
|
815
1006
|
const ranked = Array.isArray(payload.ranked) ? payload.ranked : []
|
|
816
1007
|
if (ranked.length === 0) return null
|
|
817
1008
|
try {
|
|
@@ -820,8 +1011,9 @@ async function contextPayload(root, payload, sort, kind) {
|
|
|
820
1011
|
topic: payload.topic,
|
|
821
1012
|
task: payload.task,
|
|
822
1013
|
total: payload.total,
|
|
823
|
-
// 引用图只在**真有命中**时才值得建(零命中时 Primary
|
|
824
|
-
|
|
1014
|
+
// 引用图只在**真有命中**时才值得建(零命中时 Primary 为空,邻居逻辑没有锚点);
|
|
1015
|
+
// 而且只有 Markdown 有图可建。
|
|
1016
|
+
withLinks: kind === 'doc' && ranked.some((doc) => Number(doc.raw) > 0),
|
|
825
1017
|
})
|
|
826
1018
|
return withStats(pack)
|
|
827
1019
|
} catch {
|
|
@@ -831,10 +1023,17 @@ async function contextPayload(root, payload, sort, kind) {
|
|
|
831
1023
|
}
|
|
832
1024
|
|
|
833
1025
|
/**
|
|
834
|
-
*
|
|
1026
|
+
* 读一个**可预览的文本产物**的完整正文(Markdown 文档 / 代码 / 生成产物),
|
|
1027
|
+
* 供面板内联预览。
|
|
835
1028
|
*
|
|
836
1029
|
* 路径必须落在工作区根之内——`rel` 来自浏览器,按不可信输入处理。
|
|
837
1030
|
*
|
|
1031
|
+
* v0.19:放行范围从「只认 `.md`」改成**按分类层判定**(`isPreviewKind`)。
|
|
1032
|
+
* 这条放宽是必须的(否则代码点不开),但边界一点没松:
|
|
1033
|
+
* 媒体仍然只走 `/knit/api/raw`,`ignored`(含这一版不支持的 `.go` / `.rs` / `.java`
|
|
1034
|
+
* / 未知扩展名)一律拒绝 —— **`/knit/api/doc` 仍然是按路径读文件的接口**,
|
|
1035
|
+
* 不能变成「读工作区里任意文件」的后门。
|
|
1036
|
+
*
|
|
838
1037
|
* @param {string} root - 工作区根
|
|
839
1038
|
* @param {string} rel - 工作区相对路径
|
|
840
1039
|
* @returns {Promise<object>} 载荷
|
|
@@ -846,7 +1045,9 @@ export async function readDocument(root, rel) {
|
|
|
846
1045
|
if (abs !== base && !abs.startsWith(base + sep)) {
|
|
847
1046
|
return { ok: false, code: ERROR_CODES.outsideWorkspace }
|
|
848
1047
|
}
|
|
849
|
-
|
|
1048
|
+
const name = abs.split(sep).pop() || abs
|
|
1049
|
+
const info = classifyFile(name)
|
|
1050
|
+
if (!isPreviewKind(info.kind)) return { ok: false, code: ERROR_CODES.notPreviewable }
|
|
850
1051
|
|
|
851
1052
|
let st
|
|
852
1053
|
try {
|
|
@@ -860,14 +1061,36 @@ export async function readDocument(root, rel) {
|
|
|
860
1061
|
const truncated = buf.length > DOC_MAX_BYTES
|
|
861
1062
|
const text = buf.subarray(0, DOC_MAX_BYTES).toString('utf8')
|
|
862
1063
|
|
|
863
|
-
|
|
1064
|
+
const relPath = relative(base, abs).split(sep).join('/')
|
|
1065
|
+
const payload = {
|
|
864
1066
|
ok: true,
|
|
865
|
-
rel:
|
|
866
|
-
|
|
1067
|
+
rel: relPath,
|
|
1068
|
+
// v0.19 修订:给「打开 / 定位」用的 canonical 绝对路径(展开符号链接)。
|
|
1069
|
+
// 客户端拿它去 `remote.session.openWorkspacePath`;自己用 root + rel 拼出来的那份
|
|
1070
|
+
// 一旦含符号链接就会被宿主拒掉(`Path has no verified Host path`)。
|
|
1071
|
+
path: hostPathOf(abs),
|
|
1072
|
+
// v0.19:预览分支的判据由宿主给(分类层的结论),客户端不再自己看扩展名。
|
|
1073
|
+
kind: info.kind,
|
|
1074
|
+
language: info.language,
|
|
1075
|
+
// 代码不用 `parseMarkdown` 猜标题 —— 一段开头的 `# 注释` 在 shell 里是注释,
|
|
1076
|
+
// 不是标题。代码的标题就是文件名本身。
|
|
1077
|
+
title: info.kind === KIND_DOC ? parseMarkdown(text, name).title : name,
|
|
867
1078
|
bytes: buf.length,
|
|
868
1079
|
truncated,
|
|
869
1080
|
text,
|
|
870
1081
|
}
|
|
1082
|
+
// v0.19(需求 §6 §28):同名 `<file>.map` 存在时,在 code 预览里给一个**极轻量**入口。
|
|
1083
|
+
// 只多做一次 `stat`(不读内容、不进任何列表、不进检索、不进上下文)——
|
|
1084
|
+
// `.map` 本身仍然不是 Context,这里只是「它就在旁边」这一个事实的搬运。
|
|
1085
|
+
if (info.kind === KIND_CODE && !info.sourceMap) {
|
|
1086
|
+
try {
|
|
1087
|
+
const mapStat = await stat(`${abs}.map`)
|
|
1088
|
+
if (mapStat.isFile()) payload.mapRel = `${relPath}.map`
|
|
1089
|
+
} catch {
|
|
1090
|
+
// 没有就是没有 —— 不加字段,不报错。
|
|
1091
|
+
}
|
|
1092
|
+
}
|
|
1093
|
+
return payload
|
|
871
1094
|
}
|
|
872
1095
|
|
|
873
1096
|
/**
|
|
@@ -968,6 +1191,36 @@ function rootOfSession(session) {
|
|
|
968
1191
|
return resolve(root)
|
|
969
1192
|
}
|
|
970
1193
|
|
|
1194
|
+
/**
|
|
1195
|
+
* 交给宿主去「打开 / 定位」的路径必须**展开所有符号链接**。
|
|
1196
|
+
*
|
|
1197
|
+
* 判据在 DSH 自己那里:`dsh-api-session-controller` 的 `verifyDesktopPath()` 把路径送进
|
|
1198
|
+
* `ctx.fs`,要求
|
|
1199
|
+
* `fs.processPath(await fs.resolve(fs.processPathFromHostPath(p))) === p`;
|
|
1200
|
+
* 而 `dsh-fs-local` 的 `resolve()` 落的是 `realpath()`。也就是说 ——
|
|
1201
|
+
* **路径里只要有一个符号链接没展开,宿主就回
|
|
1202
|
+
* `gateway/bad-request / Path has no verified Host path`**,
|
|
1203
|
+
* 客户端把它显示成「打开失败:Path has no verified Host path」。
|
|
1204
|
+
*
|
|
1205
|
+
* 会话的工作区根完全可能是符号链接(实测:`DSH_Skill_Trace -> 10_DSH_Skill_Trace`),
|
|
1206
|
+
* 于是「打开」这条路必须另外给一份 canonical 路径。
|
|
1207
|
+
* **显示与检索仍用会话原本那个 root** —— 用户看到的是自己选的那条路径,
|
|
1208
|
+
* 只有交给宿主打开的路径要展开。
|
|
1209
|
+
*
|
|
1210
|
+
* 文件不存在时 `realpathSync` 会抛;调用点都在 `stat` 成功之后,兜底返回原路径,
|
|
1211
|
+
* 免得把一次「打不开」升级成接口 500。
|
|
1212
|
+
*
|
|
1213
|
+
* @param {string} path - 绝对路径
|
|
1214
|
+
* @returns {string} 展开符号链接后的绝对路径
|
|
1215
|
+
*/
|
|
1216
|
+
function hostPathOf(path) {
|
|
1217
|
+
try {
|
|
1218
|
+
return realpathSync(path)
|
|
1219
|
+
} catch {
|
|
1220
|
+
return path
|
|
1221
|
+
}
|
|
1222
|
+
}
|
|
1223
|
+
|
|
971
1224
|
/**
|
|
972
1225
|
* 解析一个会话的工作区根。
|
|
973
1226
|
* @param {object} webCtx - 注入了 sessions 的上下文
|
|
@@ -1362,7 +1615,11 @@ export function apply(ctx) {
|
|
|
1362
1615
|
const limit = Math.min(Math.max(Number(url.searchParams.get('limit')) || 20, 1), 100)
|
|
1363
1616
|
const sort = url.searchParams.get('sort') === 'relevance' ? 'relevance' : 'time'
|
|
1364
1617
|
const kindParam = url.searchParams.get('kind')
|
|
1365
|
-
|
|
1618
|
+
// v0.19:多一档 `code`。白名单形态不变(认不出的值一律回落 `doc`),
|
|
1619
|
+
// 而 `context` 那个内部语料**不从 HTTP 暴露**。
|
|
1620
|
+
const kind = kindParam === 'all' || kindParam === 'media' || kindParam === 'code'
|
|
1621
|
+
? kindParam
|
|
1622
|
+
: 'doc'
|
|
1366
1623
|
const payload = await scan(root, limit, {
|
|
1367
1624
|
session: sessionOf(webCtx, sessionId), sessionId, sort, kind,
|
|
1368
1625
|
})
|
|
@@ -1410,7 +1667,9 @@ export function apply(ctx) {
|
|
|
1410
1667
|
const limit = Math.min(Math.max(Number(url.searchParams.get('limit')) || MAX_DOCS, 1), MAX_DOCS)
|
|
1411
1668
|
const sort = url.searchParams.get('sort') === 'time' ? 'time' : 'relevance'
|
|
1412
1669
|
const kindParam = url.searchParams.get('kind')
|
|
1413
|
-
const kind = kindParam === 'all' || kindParam === 'media'
|
|
1670
|
+
const kind = kindParam === 'all' || kindParam === 'media' || kindParam === 'code'
|
|
1671
|
+
? kindParam
|
|
1672
|
+
: 'doc'
|
|
1414
1673
|
const payload = await scan(root, limit, {
|
|
1415
1674
|
session: sessionOf(webCtx, sessionId), sessionId, sort, kind,
|
|
1416
1675
|
})
|
|
@@ -1430,7 +1689,7 @@ export function apply(ctx) {
|
|
|
1430
1689
|
if (sessionId && feedbackActive(sessionId)) {
|
|
1431
1690
|
auditBridge.note(sessionId, context)
|
|
1432
1691
|
}
|
|
1433
|
-
sendJson(res, 200, { ok: true, root, mode: payload.mode, topic: payload.topic, context })
|
|
1692
|
+
sendJson(res, 200, { ok: true, root, hostRoot: hostPathOf(root), mode: payload.mode, topic: payload.topic, context })
|
|
1434
1693
|
return
|
|
1435
1694
|
}
|
|
1436
1695
|
|