dsh-knit 0.4.0 → 0.5.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,6 +14,7 @@
14
14
  * 零模型、零网络出口:只读本地文件与会话日志。
15
15
  */
16
16
  import { readFile, readdir, stat } from 'node:fs/promises'
17
+ import { createReadStream } from 'node:fs'
17
18
  import { join, relative, resolve, sep } from 'node:path'
18
19
  import { homedir } from 'node:os'
19
20
  import { extractKeywords, rankByRelevance, topicLabel } from './relevance.js'
@@ -27,6 +28,8 @@ export const ROUTE_PREFIX = '/knit'
27
28
  const MAX_DEPTH = 6
28
29
  const MAX_DIRS = 500
29
30
  const MAX_DOCS = 400
31
+ /** 图片/视频等媒体产物的扫描上限(与文档分开计数,避免截图刷爆文档列表)。 */
32
+ const MAX_MEDIA = 400
30
33
  const SCAN_BUDGET_MS = 4000
31
34
  const HEAD_BYTES = 16 * 1024
32
35
  /** 单次内联预览返回的正文上限(超出截断,面板只做预览不做全量阅读)。 */
@@ -57,8 +60,31 @@ const IMAGE_TYPES = new Map([
57
60
  ['svg', 'image/svg+xml'],
58
61
  ])
59
62
 
63
+ /**
64
+ * 允许内联渲染的视频类型白名单。
65
+ * 与 IMAGE_TYPES 同样的口径:只放行表里的扩展名,/raw 不读其它任何文件。
66
+ */
67
+ const VIDEO_TYPES = new Map([
68
+ ['mp4', 'video/mp4'],
69
+ ['m4v', 'video/mp4'],
70
+ ['webm', 'video/webm'],
71
+ ['mov', 'video/quicktime'],
72
+ ['ogv', 'video/ogg'],
73
+ ])
74
+
60
75
  /** 单张内联图片的字节上限。 */
61
76
  const MAX_IMAGE_BYTES = 12 * 1024 * 1024
77
+ /**
78
+ * 单个视频的字节上限。
79
+ * Agent 生成的短视频通常几十 MB;放宽到 256MB,再大就该用系统播放器打开,
80
+ * 而不是让侧边栏扛着整段字节。
81
+ */
82
+ const MAX_VIDEO_BYTES = 256 * 1024 * 1024
83
+
84
+ /** 列表条目类型:文档 / 图片 / 视频。 */
85
+ const KIND_DOC = 'md'
86
+ const KIND_IMAGE = 'image'
87
+ const KIND_VIDEO = 'video'
62
88
 
63
89
  /**
64
90
  * 机器可读的错误码。
@@ -73,6 +99,8 @@ export const ERROR_CODES = {
73
99
  notAFile: 'knit/not-a-file',
74
100
  imageOnly: 'knit/image-only',
75
101
  imageTooLarge: 'knit/image-too-large',
102
+ mediaOnly: 'knit/media-only',
103
+ mediaTooLarge: 'knit/media-too-large',
76
104
  readFailed: 'knit/read-failed',
77
105
  missingRel: 'knit/missing-rel',
78
106
  notFoundRoute: 'knit/not-found-route',
@@ -215,19 +243,42 @@ async function readDoc(absPath) {
215
243
  }
216
244
 
217
245
  /**
218
- * 广度优先扫出工作区里的 .md 文件。
246
+ * 按扩展名判定文件是不是 Knit 要管的产物。
247
+ * @param {string} name - 文件名
248
+ * @returns {''|'md'|'image'|'video'} 类型,都不是返回空串
249
+ */
250
+ function kindOfName(name) {
251
+ const ext = (name.split('.').pop() || '').toLowerCase()
252
+ if (ext === 'md') return KIND_DOC
253
+ if (IMAGE_TYPES.has(ext)) return KIND_IMAGE
254
+ if (VIDEO_TYPES.has(ext)) return KIND_VIDEO
255
+ return ''
256
+ }
257
+
258
+ /**
259
+ * 广度优先扫出工作区里的 Markdown 与媒体文件。
260
+ *
261
+ * 一次遍历同时收两类,目录预算与时间预算共享;文档、媒体各自有数量上限,
262
+ * 截图再多也不会把文档名额挤光。
263
+ *
219
264
  * @param {string} root - 工作区根(会话 cwd)
220
- * @returns {Promise<string[]>} 绝对路径列表
265
+ * @returns {Promise<{md: string[], media: Array<{abs:string, kind:string}>,
266
+ * mdTruncated: boolean, mediaTruncated: boolean}>}
221
267
  */
222
- async function collectMarkdown(root) {
223
- const found = []
268
+ async function collectEntries(root) {
269
+ /** @type {string[]} */
270
+ const md = []
271
+ /** @type {Array<{abs:string, kind:string}>} */
272
+ const media = []
224
273
  const deadline = Date.now() + SCAN_BUDGET_MS
225
274
  /** @type {Array<{dir:string,depth:number}>} */
226
275
  const queue = [{ dir: root, depth: 0 }]
227
276
  let visited = 0
228
277
 
229
278
  while (queue.length > 0) {
230
- if (visited >= MAX_DIRS || found.length >= MAX_DOCS || Date.now() > deadline) break
279
+ if (visited >= MAX_DIRS
280
+ || (md.length >= MAX_DOCS && media.length >= MAX_MEDIA)
281
+ || Date.now() > deadline) break
231
282
  const { dir, depth } = queue.shift()
232
283
  visited += 1
233
284
 
@@ -245,41 +296,91 @@ async function collectMarkdown(root) {
245
296
  if (SKIP_DIRS.has(entry.name)) continue
246
297
  if (entry.name.startsWith('.')) continue
247
298
  queue.push({ dir: abs, depth: depth + 1 })
248
- } else if (entry.isFile() && /\.md$/i.test(entry.name)) {
249
- found.push(abs)
250
- if (found.length >= MAX_DOCS) break
299
+ } else if (entry.isFile()) {
300
+ const kind = kindOfName(entry.name)
301
+ if (kind === KIND_DOC) {
302
+ if (md.length < MAX_DOCS) md.push(abs)
303
+ } else if (kind === KIND_IMAGE || kind === KIND_VIDEO) {
304
+ if (media.length < MAX_MEDIA) media.push({ abs, kind })
305
+ }
251
306
  }
252
307
  }
253
308
  }
254
309
 
255
- return found
310
+ return {
311
+ md,
312
+ media,
313
+ mdTruncated: md.length >= MAX_DOCS,
314
+ mediaTruncated: media.length >= MAX_MEDIA,
315
+ }
256
316
  }
257
317
 
258
318
  /**
259
- * 扫出工作区里全部 Markdown 的元信息(按 mtime 倒序)。
319
+ * 读一个媒体文件的元信息(只 stat,绝不读内容 —— 视频可能上百 MB)。
260
320
  * @param {string} root - 工作区根
261
- * @returns {Promise<{docs: Array<object>, truncated: boolean}>} 文档列表
321
+ * @param {{abs:string, kind:string}} item - 扫描阶段记下的媒体项
322
+ * @returns {Promise<object|null>} 列表记录,读失败返回 null
323
+ */
324
+ async function readMediaMeta(root, { abs, kind }) {
325
+ let st
326
+ try {
327
+ st = await stat(abs)
328
+ } catch {
329
+ return null
330
+ }
331
+ if (!st.isFile()) return null
332
+
333
+ const name = abs.split(sep).pop() || abs
334
+ return {
335
+ kind,
336
+ path: abs,
337
+ rel: relative(root, abs).split(sep).join('/'),
338
+ name,
339
+ // 没有正文可解析,标题就用文件名(去扩展名)。
340
+ title: name.replace(/\.[^.]+$/, ''),
341
+ summary: '',
342
+ size: st.size,
343
+ mtimeMs: st.mtimeMs,
344
+ // 媒体只能靠文件名参与相关性匹配(镜头名、截图名里的关键词)。
345
+ haystack: { title: name.toLowerCase(), summary: '', body: '' },
346
+ }
347
+ }
348
+
349
+ /**
350
+ * 扫出工作区里全部 Markdown 与媒体的元信息(各自按 mtime 倒序)。
351
+ * @param {string} root - 工作区根
352
+ * @returns {Promise<{docs: Array<object>, media: Array<object>,
353
+ * truncated: boolean, mediaTruncated: boolean}>}
262
354
  */
263
355
  export async function collectDocs(root) {
264
- const files = await collectMarkdown(root)
356
+ const found = await collectEntries(root)
265
357
  const docs = []
266
358
 
267
- for (const abs of files) {
359
+ for (const abs of found.md) {
268
360
  const meta = await readDoc(abs)
269
361
  if (!meta) continue
270
362
  docs.push({
363
+ kind: KIND_DOC,
271
364
  path: abs,
272
365
  rel: relative(root, abs).split(sep).join('/'),
273
366
  name: abs.split(sep).pop(),
274
367
  title: meta.title,
275
368
  summary: meta.summary,
369
+ size: meta.size,
276
370
  mtimeMs: meta.mtimeMs,
277
371
  haystack: { title: meta.hayTitle, summary: meta.haySummary, body: meta.hayBody },
278
372
  })
279
373
  }
280
-
281
374
  docs.sort((a, b) => b.mtimeMs - a.mtimeMs)
282
- return { docs, truncated: files.length >= MAX_DOCS }
375
+
376
+ const media = []
377
+ for (const item of found.media) {
378
+ const meta = await readMediaMeta(root, item)
379
+ if (meta) media.push(meta)
380
+ }
381
+ media.sort((a, b) => b.mtimeMs - a.mtimeMs)
382
+
383
+ return { docs, media, truncated: found.mdTruncated, mediaTruncated: found.mediaTruncated }
283
384
  }
284
385
 
285
386
  /* ── 会话事件 → 对话文本 ────────────────────────────── */
@@ -372,11 +473,13 @@ function keywordsFor(session, sessionId) {
372
473
  */
373
474
  function publicDoc(doc) {
374
475
  return {
476
+ kind: doc.kind || KIND_DOC,
375
477
  path: doc.path,
376
478
  rel: doc.rel,
377
479
  name: doc.name,
378
480
  title: doc.title,
379
481
  summary: doc.summary,
482
+ size: typeof doc.size === 'number' ? doc.size : null,
380
483
  mtimeMs: doc.mtimeMs,
381
484
  score: typeof doc.score === 'number' ? doc.score : null,
382
485
  }
@@ -387,11 +490,27 @@ function publicDoc(doc) {
387
490
  *
388
491
  * @param {string} root - 工作区根
389
492
  * @param {number} limit - 最多返回多少条
390
- * @param {{session?: object, sessionId?: string, sort?: string}} options - 排序上下文
493
+ * @param {{session?: object, sessionId?: string, sort?: string, kind?: string}} options -
494
+ * 排序上下文;`kind` 为 `doc`(默认,仅 Markdown)、`media`(仅图片/视频)或 `all`
391
495
  * @returns {Promise<object>} 给浏览器的载荷
392
496
  */
393
497
  export async function scan(root, limit, options = {}) {
394
- const { docs, truncated } = await collectDocs(root)
498
+ const collected = await collectDocs(root)
499
+
500
+ // 默认 doc:旧版客户端 / 悬停浮层不带 kind,行为与「只列 Markdown」时完全一致。
501
+ const kind = options.kind === 'all' || options.kind === 'media' ? options.kind : 'doc'
502
+ let pool
503
+ let truncated
504
+ if (kind === 'media') {
505
+ pool = collected.media
506
+ truncated = collected.mediaTruncated
507
+ } else if (kind === 'all') {
508
+ pool = collected.docs.concat(collected.media).sort((a, b) => b.mtimeMs - a.mtimeMs)
509
+ truncated = collected.truncated || collected.mediaTruncated
510
+ } else {
511
+ pool = collected.docs
512
+ truncated = collected.truncated
513
+ }
395
514
 
396
515
  const wantRelevance = options.sort === 'relevance'
397
516
  const sessionId = options.sessionId || ''
@@ -405,12 +524,13 @@ export async function scan(root, limit, options = {}) {
405
524
  }
406
525
 
407
526
  const ordered = mode === 'relevance'
408
- ? rankByRelevance(docs, keywords, Date.now()).docs
409
- : docs.map((doc) => ({ ...doc, score: null }))
527
+ ? rankByRelevance(pool, keywords, Date.now()).docs
528
+ : pool.map((doc) => ({ ...doc, score: null }))
410
529
 
411
530
  return {
412
531
  ok: true,
413
532
  root,
533
+ kind,
414
534
  total: ordered.length,
415
535
  truncated,
416
536
  sessionId,
@@ -462,16 +582,18 @@ export async function readDocument(root, rel) {
462
582
  }
463
583
 
464
584
  /**
465
- * 读一张内联图片的字节,供预览里的相对路径图片渲染。
585
+ * 解析一个媒体(图片/视频)路径:越界防护 + 扩展名白名单 + 类型与大小校验。
586
+ *
587
+ * 这是按路径读文件的接口,不设限就等于开了读任意文件的后门:路径必须落在工作区内,
588
+ * 扩展名必须在图片/视频白名单里,视频还有单独的大小上限。
466
589
  *
467
- * 与 `readDocument` 同样的越界防护,再叠一层扩展名白名单 —— 这是按路径读文件的接口,
468
- * 不设限就等于开了一个读任意文件的后门。
590
+ * 只 stat、不读字节 —— 视频可能上百 MB,字节交给流式接口按需读取。
469
591
  *
470
592
  * @param {string} root - 工作区根
471
593
  * @param {string} rel - 工作区相对路径
472
- * @returns {Promise<object>} 成功时带 `type` 与 `bytes`
594
+ * @returns {Promise<object>} 成功时带 `{ abs, kind, type, size }`,否则带错误码
473
595
  */
474
- export async function readImage(root, rel) {
596
+ export async function mediaInfo(root, rel) {
475
597
  const base = resolve(root)
476
598
  const abs = resolve(base, rel)
477
599
  if (abs !== base && !abs.startsWith(base + sep)) {
@@ -479,8 +601,13 @@ export async function readImage(root, rel) {
479
601
  }
480
602
 
481
603
  const ext = (abs.split('.').pop() || '').toLowerCase()
482
- const type = IMAGE_TYPES.get(ext)
483
- if (!type) return { ok: false, code: ERROR_CODES.imageOnly }
604
+ let kind = KIND_IMAGE
605
+ let type = IMAGE_TYPES.get(ext)
606
+ if (!type) {
607
+ kind = KIND_VIDEO
608
+ type = VIDEO_TYPES.get(ext)
609
+ }
610
+ if (!type) return { ok: false, code: ERROR_CODES.mediaOnly }
484
611
 
485
612
  let st
486
613
  try {
@@ -489,14 +616,47 @@ export async function readImage(root, rel) {
489
616
  return { ok: false, code: ERROR_CODES.notFound }
490
617
  }
491
618
  if (!st.isFile()) return { ok: false, code: ERROR_CODES.notAFile }
492
- if (st.size > MAX_IMAGE_BYTES) return { ok: false, code: ERROR_CODES.imageTooLarge }
619
+ if (kind === KIND_IMAGE && st.size > MAX_IMAGE_BYTES) {
620
+ return { ok: false, code: ERROR_CODES.imageTooLarge }
621
+ }
622
+ if (kind === KIND_VIDEO && st.size > MAX_VIDEO_BYTES) {
623
+ return { ok: false, code: ERROR_CODES.mediaTooLarge }
624
+ }
493
625
 
494
- try {
495
- const bytes = await readFile(abs)
496
- return { ok: true, type, bytes }
497
- } catch {
498
- return { ok: false, code: ERROR_CODES.readFailed }
626
+ return { ok: true, abs, kind, type, size: st.size }
627
+ }
628
+
629
+ /**
630
+ * 解析 HTTP Range 头(只支持 bytes 的单区间,覆盖 `<video>` 首帧与拖动播放的请求形态)。
631
+ *
632
+ * 解析不了(无 Range、多区间、语法怪异)一律返回 null —— 调用方回退成 200 整文件,
633
+ * 而不是因为一个边角 Range 把播放掐死。
634
+ *
635
+ * @param {string|undefined} header - Range 头原值
636
+ * @param {number} size - 文件总字节
637
+ * @returns {{start:number,end:number}|null} 闭区间字节范围;null 表示返回整个文件
638
+ */
639
+ export function parseRange(header, size) {
640
+ if (!header || size <= 0) return null
641
+ const m = /^bytes=(\d*)-(\d*)$/.exec(String(header).trim())
642
+ if (!m) return null
643
+ const startRaw = m[1]
644
+ const endRaw = m[2]
645
+ if (startRaw === '' && endRaw === '') return null
646
+
647
+ // bytes=-N:最后 N 个字节
648
+ if (startRaw === '') {
649
+ const suffix = Number(endRaw)
650
+ if (!Number.isInteger(suffix) || suffix <= 0) return null
651
+ return { start: Math.max(0, size - suffix), end: size - 1 }
499
652
  }
653
+
654
+ const start = Number(startRaw)
655
+ if (!Number.isInteger(start) || start < 0 || start >= size) return null
656
+ let end = endRaw === '' ? size - 1 : Number(endRaw)
657
+ if (!Number.isInteger(end) || end < start) end = size - 1
658
+ end = Math.min(end, size - 1)
659
+ return { start, end }
500
660
  }
501
661
 
502
662
  /**
@@ -561,25 +721,46 @@ function sendJson(res, status, body) {
561
721
  }
562
722
 
563
723
  /**
564
- * 写一个二进制响应(内联图片用)。
724
+ * 流式回一个媒体文件(图片/视频),支持 HTTP Range(206 Partial Content)。
565
725
  *
566
- * 安全头是刻意的:`nosniff` 防止浏览器把非图片当图片猜类型;
567
- * `default-src 'none'` 让 SVG 里的脚本、外链一并失效 —— 即使它被直接打开也跑不起来。
726
+ * 视频首帧与拖动播放都依赖 Range:一次性把上百 MB 读进内存再返回既慢又占内存;
727
+ * createReadStream 按区间读,客户端断开就销毁流。安全头与原图片接口一致:
728
+ * nosniff 防类型嗅探,default-src 'none' + sandbox 让 SVG 脚本/外链失效。
568
729
  *
730
+ * @param {import('node:http').IncomingMessage} req - 请求对象
569
731
  * @param {import('node:http').ServerResponse} res - 响应对象
570
- * @param {string} type - Content-Type
571
- * @param {Buffer} bytes - 文件字节
732
+ * @param {{abs:string, type:string, size:number}} info - mediaInfo 的成功结果
572
733
  * @returns {void}
573
734
  */
574
- function sendBytes(res, type, bytes) {
575
- res.writeHead(200, {
576
- 'content-type': type,
577
- 'content-length': bytes.length,
735
+ function sendMedia(req, res, info) {
736
+ const part = parseRange(req.headers.range, info.size)
737
+ /** @type {Record<string, string|number>} */
738
+ const headers = {
739
+ 'content-type': info.type,
740
+ 'accept-ranges': 'bytes',
578
741
  'cache-control': 'no-store',
579
742
  'x-content-type-options': 'nosniff',
580
743
  'content-security-policy': "default-src 'none'; sandbox",
744
+ }
745
+
746
+ let stream
747
+ if (part) {
748
+ headers['content-range'] = `bytes ${part.start}-${part.end}/${info.size}`
749
+ headers['content-length'] = part.end - part.start + 1
750
+ res.writeHead(206, headers)
751
+ stream = createReadStream(info.abs, { start: part.start, end: part.end })
752
+ } else {
753
+ headers['content-length'] = info.size
754
+ res.writeHead(200, headers)
755
+ stream = createReadStream(info.abs)
756
+ }
757
+
758
+ stream.on('error', () => {
759
+ try { stream.destroy() } catch { /* 已关闭 */ }
760
+ try { res.destroy() } catch { /* 已关闭 */ }
581
761
  })
582
- res.end(bytes)
762
+ req.on('close', () => { try { stream.destroy() } catch { /* 已关闭 */ } })
763
+ stream.pipe(res)
583
764
  }
584
765
 
585
766
  /**
@@ -607,7 +788,11 @@ export function apply(ctx) {
607
788
  if (url.pathname === `${ROUTE_PREFIX}/api/recent`) {
608
789
  const limit = Math.min(Math.max(Number(url.searchParams.get('limit')) || 20, 1), 100)
609
790
  const sort = url.searchParams.get('sort') === 'relevance' ? 'relevance' : 'time'
610
- const payload = await scan(root, limit, { session: sessionOf(webCtx, sessionId), sessionId, sort })
791
+ const kindParam = url.searchParams.get('kind')
792
+ const kind = kindParam === 'all' || kindParam === 'media' ? kindParam : 'doc'
793
+ const payload = await scan(root, limit, {
794
+ session: sessionOf(webCtx, sessionId), sessionId, sort, kind,
795
+ })
611
796
  sendJson(res, 200, payload)
612
797
  return
613
798
  }
@@ -629,12 +814,12 @@ export function apply(ctx) {
629
814
  sendJson(res, 400, { ok: false, code: ERROR_CODES.missingRel })
630
815
  return
631
816
  }
632
- const image = await readImage(root, rel)
633
- if (!image.ok) {
634
- sendJson(res, 404, { ok: false, code: image.code })
817
+ const media = await mediaInfo(root, rel)
818
+ if (!media.ok) {
819
+ sendJson(res, 404, { ok: false, code: media.code })
635
820
  return
636
821
  }
637
- sendBytes(res, image.type, image.bytes)
822
+ sendMedia(req, res, media)
638
823
  return
639
824
  }
640
825