dsh-knit 0.20.0 → 0.22.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/tool.js CHANGED
@@ -50,6 +50,11 @@ const SUMMARY_CHARS = 90
50
50
  */
51
51
  const SNIPPET_CHARS = 200
52
52
 
53
+ // v0.21:工具侧的每项关系上限(面板是 3,工具更贵 ⇒ 2)。
54
+ // 常量只有一处真源(`relations.js`),这里不抄一份 —— 抄一份就必然漂。
55
+ import { MAX_TOOL_RELATIONS_PER_ITEM } from './relations.js'
56
+
57
+
53
58
  /**
54
59
  * 单文件参与检索的上限(KB)。
55
60
  *
@@ -176,6 +181,33 @@ const ITEM_SCHEMA = {
176
181
  // 所以它是 required,不是 optional —— schema 要如实描述。
177
182
  required: ['code', 'terms', 'fields', 'term'],
178
183
  },
184
+ // v0.21:**来源**(怎么进的这个包)。与上面的 `source`(文件角色)是两件事,
185
+ // 名字故意不同 —— 把 `source` 的语义换掉会静默打断老调用方。
186
+ // retrieval = 命中当前任务的关键词;relation = 靠关系进来;manual = 用户自己钉的。
187
+ provenance: { type: 'string', enum: ['retrieval', 'relation', 'manual'] },
188
+ // v0.21:**这个条目与工作区里别的文件的关系**(需求 §6.7)。
189
+ // 每条都带证据:`other` 是对方 rel,`line` 是**提及所在那一行**(1 起)。
190
+ // dir:'out' ⇒ 本条目提到了 other,`line` 在本条目里
191
+ // dir:'in' ⇒ other 提到了本条目,`line` 在 other 里
192
+ // `tests` 是唯一没有 `line` 的一类:它的证据是文件名约定,不是某一行文字。
193
+ // **可选**(没有关系时键不出现,而不是给空数组),且也**不是全集** ——
194
+ // 最多 `MAX_TOOL_RELATIONS_PER_ITEM`(2)条,按类型的证据强度截断。
195
+ relations: {
196
+ type: 'array',
197
+ items: {
198
+ type: 'object',
199
+ additionalProperties: false,
200
+ properties: {
201
+ type: { type: 'string', enum: ['references', 'imports', 'tests', 'documents'] },
202
+ dir: { type: 'string', enum: ['in', 'out'] },
203
+ other: { type: 'string' },
204
+ line: { type: 'integer' },
205
+ },
206
+ required: ['type', 'dir', 'other'],
207
+ },
208
+ },
209
+ // 截断前的真实条数(`relations` 只是投影出来的一小段)。只有被截断时才有。
210
+ relationsTotal: { type: 'integer' },
179
211
  // v0.11:命中的那一小段**原文**(不是整篇)。**可选** ——
180
212
  // 时间序模式没有命中词,抽不出来就不带这个字段,
181
213
  // 而不是给个空串假装有。
@@ -209,7 +241,8 @@ const ITEM_SCHEMA = {
209
241
  },
210
242
  // `kind` 也是 required:`buildContext()` 每条都给了(取不到时回落 `'md'`)。
211
243
  // 声明成可选就等于允许「有的条目有 kind、有的没有」这种形状漂移。
212
- required: ['rel', 'title', 'summary', 'mtimeMs', 'kind', 'source', 'reason'],
244
+ // v0.21 起 `provenance` 也是 —— 装配层每条都算得出来(`retrieval` 是兜底值)。
245
+ required: ['rel', 'title', 'summary', 'mtimeMs', 'kind', 'source', 'reason', 'provenance'],
213
246
  }
214
247
 
215
248
  const OUTPUT_SCHEMA = {
@@ -226,6 +259,10 @@ const OUTPUT_SCHEMA = {
226
259
  primary: { type: 'array', items: ITEM_SCHEMA },
227
260
  supporting: { type: 'array', items: ITEM_SCHEMA },
228
261
  related: { type: 'array', items: ITEM_SCHEMA },
262
+ // v0.21:**用户亲手固定**的条目(实现说明 §9)。它们已经**从三层移出**,
263
+ // 所以三层里不会再出现同一条 —— 面板与工具用的是同一份装配结果。
264
+ // 可选:没有固定项时这个键不出现(老调用方一字不受影响)。
265
+ pinned: { type: 'array', items: ITEM_SCHEMA },
229
266
  // 渲染头部那条「N matching documents」用的计数。**它不是分数** ——
230
267
  // 只是「本批语料里命中了几篇 / 一共有几篇」,给模型一个「有没有漏」的锚。
231
268
  // 只有 relevance 模式有,所以不在 `required` 里。
@@ -446,10 +483,13 @@ export function renderToolText(value, readSnippet) {
446
483
  const primary = (value && Array.isArray(value.primary)) ? value.primary : []
447
484
  const supporting = (value && Array.isArray(value.supporting)) ? value.supporting : []
448
485
  const related = (value && Array.isArray(value.related)) ? value.related : []
486
+ // v0.21:用户固定项(实现说明 §9)。它们**已经不在三层里**,所以不会重复出现。
487
+ const pinned = (value && Array.isArray(value.pinned)) ? value.pinned : []
449
488
 
450
489
  // 三层都空 = 真的没有可看的上下文。**不能只判 total** —— 工作区有文档、
451
490
  // 但当前话题一篇都没命中、且一条引用邻居都没有时,`total` 是正数而三层全空。
452
- if (primary.length + supporting.length + related.length === 0) {
491
+ // ⚠️ v0.21:三层空但**有固定项**时不算空 —— 用户亲手钉的那几篇就是这一轮的全部上下文。
492
+ if (primary.length + supporting.length + related.length + pinned.length === 0) {
453
493
  if (total === 0) return EMPTY
454
494
  // 文档在、但一个词都没命中 —— **不许说成「工作区里没有文档」**:
455
495
  // 那是一句假话,而且会把 agent 推向一个错的结论(「这个项目里没有相关材料」)。
@@ -495,13 +535,44 @@ export function renderToolText(value, readSnippet) {
495
535
  * 它走本地 HTTP、不进模型上下文,需求 §11 的「可带多段」在那里成立。
496
536
  * 这也正对需求 §15 的措辞:给的是「**最相关片段**」(单数)+ 文件 + 理由。
497
537
  */
538
+ /**
539
+ * 一项的**关系**(v0.21,需求 §6.7 / §9)。
540
+ *
541
+ * 形状是刻意压到最小的:一条事实 = `类型 箭头 对方路径[:行号]`,最多 2 条,一行说完。
542
+ * · 箭头是**方向**:`→` 本条目提到了对方;`←` 对方提到了本条目。
543
+ * (只写类型不写方向,模型会把「被引用」读成「引用了」,那是两件相反的事。)
544
+ * · 行号是**证据**:拿到它就能直接去读那一行,不必重新搜。
545
+ * · **不写理由文案**(「因为它被主文档引用」那种话由 `reason` 承担),
546
+ * 关系这一行只给可核验的事实 —— 文案越长越容易变成解释而不是证据。
547
+ * · 没有关系就不渲染这一行(不写「无」)。`tests` 天生没有行号,也不编一个。
548
+ *
549
+ * 上限由 `relations.js` 的 `MAX_TOOL_RELATIONS_PER_ITEM` 定,`project()` 已截过一次,
550
+ * 这里再截一次是**冗余的保险**:`renderToolText()` 是导出函数,可能被直接喂一份
551
+ * 手写的 value(测试就这么干),那时它必须自己守住预算。
552
+ */
553
+ const relationLine = (item) => {
554
+ const list = item && Array.isArray(item.relations) ? item.relations : []
555
+ return list
556
+ .slice(0, MAX_TOOL_RELATIONS_PER_ITEM)
557
+ .map((r) => {
558
+ if (!r || !r.other) return ''
559
+ const arrow = r.dir === 'in' ? '←' : '→'
560
+ const at = Number.isInteger(r.line) ? `:${r.line}` : ''
561
+ return `${String(r.type || 'related')} ${arrow} ${r.other}${at}`
562
+ })
563
+ .filter(Boolean)
564
+ .join('; ')
565
+ }
566
+
498
567
  const lines = (items) => items.map((item, index) => {
499
568
  const summary = oneLine(item.summary)
500
569
  const why = whyText(item.reason)
501
570
  const snippet = matchLine(item)
571
+ const links = relationLine(item)
502
572
  return `${index + 1}. ${item.rel} — ${item.title}`
503
573
  + `${summary ? `\n ${summary}` : ''}`
504
574
  + `${why ? `\n Why: ${why}` : ''}`
575
+ + `${links ? `\n relations: ${links}` : ''}`
505
576
  + `${snippet ? `\n match: ${snippet}` : ''}`
506
577
  })
507
578
 
@@ -513,6 +584,11 @@ export function renderToolText(value, readSnippet) {
513
584
  + 'primary / supporting / related by deterministic local rules (first-read order — '
514
585
  + 'not a flat relevance list; each tier is still ranked by IDF-weighted relevance):')
515
586
 
587
+ // v0.21:固定项排在最前 —— 它是**用户的话**,比任何排序都硬(实现说明 §6)。
588
+ // 放在三层之前是有语义的:模型先看到「这个人要求我一直带着的几篇」。
589
+ if (pinned.length > 0) {
590
+ out.push('', 'Pinned by the user (always in scope, in the order they were pinned):', ...lines(pinned))
591
+ }
516
592
  if (primary.length > 0) {
517
593
  out.push('', 'Primary (read these first):', ...lines(primary))
518
594
  }
@@ -717,11 +793,21 @@ export function knitDocsDefinition(scan, read, contextFor, audit) {
717
793
  * `integer` —— v0.14 把三层条目**原样透传**过一次,于是 `knit_docs` 每次调用
718
794
  * 都在校验层失败(`"value.primary[0].mtimeMs" must be an integer`),
719
795
  * agent 一个 Context Pack 都拿不到。时间序那条分支一直是取整的,两边不一致。
796
+ *
797
+ * v0.21:关系在这里再截一次(面板给 3,工具只给 2)。被截掉时把**真实总数**
798
+ * 写进 `relationsTotal` —— 模型要知道「这不是全部」,而不是以为那就是全部关系。
720
799
  */
721
- const project = (item) => ({
722
- ...item,
723
- mtimeMs: Number.isFinite(item.mtimeMs) ? Math.trunc(item.mtimeMs) : 0,
724
- })
800
+ const project = (item) => {
801
+ const row = {
802
+ ...item,
803
+ mtimeMs: Number.isFinite(item.mtimeMs) ? Math.trunc(item.mtimeMs) : 0,
804
+ }
805
+ if (Array.isArray(row.relations) && row.relations.length > MAX_TOOL_RELATIONS_PER_ITEM) {
806
+ row.relationsTotal = Number.isInteger(row.relationsTotal) ? row.relationsTotal : row.relations.length
807
+ row.relations = row.relations.slice(0, MAX_TOOL_RELATIONS_PER_ITEM)
808
+ }
809
+ return row
810
+ }
725
811
 
726
812
  // v0.20:命中片段**在 `scan()` 里就算好了**(`payload.ranked[].matches`,带行号),
727
813
  // 键是 `rel`。有片段就不再读盘 —— 这是顺带拿到的性能收益:v0.19 为了抽 200 字,
@@ -773,6 +859,10 @@ export function knitDocsDefinition(scan, read, contextFor, audit) {
773
859
  primary: await withSnippets(pack.primary || []),
774
860
  supporting: await withSnippets(pack.supporting || []),
775
861
  related: await withSnippets(pack.related || []),
862
+ // v0.21:用户固定项。**没有就一个键都不加**(老调用方的输出形状一字不变)。
863
+ ...(Array.isArray(pack.pinned) && pack.pinned.length > 0
864
+ ? { pinned: await withSnippets(pack.pinned) }
865
+ : {}),
776
866
  // 只有 `audit: true` 且真的取到摘要时才有这个字段(否则连键都不出现)
777
867
  ...(usage ? { usage } : {}),
778
868
  }