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/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
- const KIND_DOC = 'md'
122
- const KIND_IMAGE = 'image'
123
- const KIND_VIDEO = 'video'
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
- markdownOnly: 'knit/markdown-only',
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
- * 按扩展名判定文件是不是 Knit 要管的产物。
286
- * @param {string} name - 文件名
287
- * @returns {''|'md'|'image'|'video'} 类型,都不是返回空串
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 kindOfName(name) {
290
- const ext = (name.split('.').pop() || '').toLowerCase()
291
- if (ext === 'md') return KIND_DOC
292
- if (IMAGE_TYPES.has(ext)) return KIND_IMAGE
293
- if (VIDEO_TYPES.has(ext)) return KIND_VIDEO
294
- return ''
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
- * 广度优先扫出工作区里的 Markdown 与媒体文件。
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 = Date.now() + SCAN_BUDGET_MS
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 kind = kindOfName(entry.name)
340
- if (kind === KIND_DOC) {
341
- if (md.length < MAX_DOCS) md.push(abs)
342
- } else if (kind === KIND_IMAGE || kind === KIND_VIDEO) {
343
- if (media.length < MAX_MEDIA) media.push({ abs, kind })
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
- * 扫出工作区里全部 Markdown 与媒体的元信息(各自按 mtime 倒序)。
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 { docs, media, truncated: found.mdTruncated, mediaTruncated: found.mediaTruncated }
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
- const collected = await collectDocs(root)
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
- const kind = options.kind === 'all' || options.kind === 'media' ? options.kind : 'doc'
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.media).sort((a, b) => b.mtimeMs - a.mtimeMs)
620
- truncated = collected.truncated || collected.mediaTruncated
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 - 本次扫描到的文档(按 rel)
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 () => ({ docs: [...byRel.values()], truncated: false }),
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
- * **只在文档档 + 相关序 + 有命中词时装配** —— 其余情形返回 null,
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
- if (!payload || payload.mode !== 'relevance' || sort !== 'relevance' || kind !== 'doc') return null
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
- withLinks: ranked.some((doc) => Number(doc.raw) > 0),
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
- if (!/\.md$/i.test(abs)) return { ok: false, code: ERROR_CODES.markdownOnly }
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
- return {
1064
+ const relPath = relative(base, abs).split(sep).join('/')
1065
+ const payload = {
864
1066
  ok: true,
865
- rel: relative(base, abs).split(sep).join('/'),
866
- title: parseMarkdown(text, abs.split(sep).pop() || abs).title,
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
- const kind = kindParam === 'all' || kindParam === 'media' ? kindParam : 'doc'
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' ? kindParam : 'doc'
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