dsh-knit 0.14.0 → 0.15.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
@@ -26,6 +26,12 @@ import { buildLinkGraph, linksOf } from './links.js'
26
26
  // `renderToolText()` 里发生(模型看到的是那段文本,不是结构化 JSON)。曾经多导出一个
27
27
  // `renderContextText` 却没人调用 —— 那是个会与 `tool.js` 漂移的第二渲染器,已删。
28
28
  import { buildContext } from './context.js'
29
+ // v0.15:Context Feedback / Context Audit —— 「Context Pack 之后真的被用了吗」。
30
+ // ⚠️ 只做三件确定性的事:从会话事件里抽**真实的 `read`**、把交出去的包记成 Snapshot、
31
+ // 把两者接起来算 Usage。**不订阅 event bus、不落盘、不联网、不调模型、不改 Retrieval。**
32
+ import {
33
+ createStore, activateAudit, isAudited, ingestEvents, noteSnapshot, usageFor, getAuditSummary,
34
+ } from './feedback.js'
29
35
 
30
36
  export const name = 'dsh-knit'
31
37
 
@@ -1041,6 +1047,130 @@ function sendMedia(req, res, info) {
1041
1047
  stream.pipe(res)
1042
1048
  }
1043
1049
 
1050
+ /* ── v0.15 · Context Feedback 的宿主侧封装 ────────────────────────────
1051
+ *
1052
+ * 这一层只做三件事:
1053
+ * 1. 从 `session.snapshotEvents()` **拉**事件(不订阅任何总线)喂给 feedback store;
1054
+ * 2. 把刚交出去的 Context Pack 记成 Context Snapshot;
1055
+ * 3. 给面板与 `knit_docs` 提供「**上一份**包之后发生了什么」。
1056
+ *
1057
+ * 记账只在**被显式打开**的会话里发生(面板的「使用情况」开关,或 `knit_docs` 的
1058
+ * `audit: true`)—— 默认一个字节都不攒。所有入口都 try/catch:
1059
+ * 记账坏了不许影响面板与工具(规格 §33 的降级纪律)。
1060
+ */
1061
+
1062
+ /** 进程内唯一的 feedback store(按会话分片,会话数与篇数都有硬上限)。 */
1063
+ const feedbackStore = createStore()
1064
+
1065
+ /**
1066
+ * 安全读会话事件。拿不到返回 `null` 而**不是空数组** —— 空数组会被下游当成
1067
+ * 「这个会话真的没有任何事件」,那是两件不同的事。
1068
+ * @param {object} session - 宿主会话
1069
+ * @returns {object[]|null} 事件数组或 null
1070
+ */
1071
+ function sessionEvents(session) {
1072
+ try {
1073
+ if (!session || typeof session.snapshotEvents !== 'function') return null
1074
+ const events = session.snapshotEvents()
1075
+ return Array.isArray(events) ? events : null
1076
+ } catch {
1077
+ return null
1078
+ }
1079
+ }
1080
+
1081
+ /**
1082
+ * 把会话事件喂给 feedback store。幂等靠 `seq` 游标 —— 面板每 5 秒轮询一次,
1083
+ * 每次都会把**同一批历史事件**再拉一遍,游标保证同一篇读只记一次。
1084
+ * @param {string} root - 工作区根(归一化绝对路径用)
1085
+ * @param {string} sessionId - 会话 id
1086
+ * @param {object} session - 宿主会话
1087
+ * @returns {{ok: boolean, reads: number, cursor: number}} 结果
1088
+ */
1089
+ function ingestFeedback(root, sessionId, session) {
1090
+ const events = sessionEvents(session)
1091
+ if (!events || !sessionId) return { ok: false, reads: 0, cursor: -1 }
1092
+ return ingestEvents(feedbackStore, sessionId, events, { root })
1093
+ }
1094
+
1095
+ /**
1096
+ * 打开某个会话的记账(面板的「使用情况」开关走它)。
1097
+ * @param {string} sessionId - 会话 id
1098
+ * @returns {boolean} 是否成功
1099
+ */
1100
+ export function activateFeedback(sessionId) {
1101
+ return activateAudit(feedbackStore, sessionId)
1102
+ }
1103
+
1104
+ /**
1105
+ * 这个会话在记账吗。
1106
+ * @param {string} sessionId - 会话 id
1107
+ * @returns {boolean} 是否记账
1108
+ */
1109
+ export function feedbackActive(sessionId) {
1110
+ return isAudited(feedbackStore, sessionId)
1111
+ }
1112
+
1113
+ /**
1114
+ * 线路上的紧凑使用情况:面板只需要**计数**与最近一次变化,不需要 200 条明细。
1115
+ * @param {object|null} usage - `usageFor()` 的结果
1116
+ * @param {number} [limit] - 明细最多带几条
1117
+ * @returns {object|null} 紧凑视图
1118
+ */
1119
+ export function publicUsage(usage, limit = 20) {
1120
+ if (!usage || !usage.stats) return null
1121
+ return {
1122
+ at: usage.at,
1123
+ stats: { ...usage.stats, outsideReads: usage.stats.outsideReads.slice(0, limit) },
1124
+ delta: usage.delta ? {
1125
+ appeared: usage.delta.appeared.slice(0, limit),
1126
+ disappeared: usage.delta.disappeared.slice(0, limit),
1127
+ moved: usage.delta.moved.slice(0, limit),
1128
+ taskChanged: !!usage.delta.taskChanged,
1129
+ } : null,
1130
+ }
1131
+ }
1132
+
1133
+ /**
1134
+ * 注入给 `knit_docs` 的桥 —— 工具不认识 `feedback.js`,只认识这两个方法
1135
+ * (与 `scan` / `read` / `contextFor` 同样的注入理由)。
1136
+ * ⚠️ `summary()` 必须在 `note()` **之前**调用:它报告的是**上一份**包的用法。
1137
+ */
1138
+ const auditBridge = {
1139
+ usage(root, sessionId, session) {
1140
+ try {
1141
+ if (!sessionId) return null
1142
+ ingestFeedback(root, sessionId, session)
1143
+ return usageFor(feedbackStore, sessionId)
1144
+ } catch {
1145
+ return null
1146
+ }
1147
+ },
1148
+ summary(root, sessionId, session) {
1149
+ try {
1150
+ if (!sessionId) return ''
1151
+ ingestFeedback(root, sessionId, session)
1152
+ return getAuditSummary(usageFor(feedbackStore, sessionId))
1153
+ } catch {
1154
+ return ''
1155
+ }
1156
+ },
1157
+ note(root, sessionId, session, pack) {
1158
+ try {
1159
+ if (!sessionId || !pack) return null
1160
+ // 走到这里说明记账是**显式**的(面板带了 `usage=1`,或 agent 传了 `audit: true`
1161
+ // 且 `tool.js` 只在那一刻调 note)—— 所以在这里开闸是安全的。
1162
+ activateAudit(feedbackStore, sessionId)
1163
+ const { cursor } = ingestFeedback(root, sessionId, session)
1164
+ return noteSnapshot(feedbackStore, sessionId, pack, {
1165
+ seq: Number.isInteger(cursor) ? cursor : -1,
1166
+ at: Date.now(),
1167
+ })
1168
+ } catch {
1169
+ return null
1170
+ }
1171
+ },
1172
+ }
1173
+
1044
1174
  /**
1045
1175
  * 宿主插件体:等 webServer / sessions 到位后挂只读路由。
1046
1176
  * @param {import('@deepseek-ai/cordis').Context} ctx - 宿主根上下文
@@ -1075,6 +1205,16 @@ export function apply(ctx) {
1075
1205
  // v0.14:相关模式下顺带给出任务上下文分层。
1076
1206
  // ⚠️ 带上 `context` 是**可选**的(老客户端忽略它),而 `docs` 一字未动。
1077
1207
  body.context = await contextPayload(root, payload, sort, kind)
1208
+ // v0.15:面板把「使用情况」开关打开后,请求会带 `usage=1` —— 那一刻开始记账。
1209
+ // ⚠️ 默认(不带这个参数且本会话从未打开过)**一个字节都不记**。
1210
+ if (sessionId && url.searchParams.get('usage') === '1') activateFeedback(sessionId)
1211
+ if (sessionId && feedbackActive(sessionId)) {
1212
+ const session = sessionOf(webCtx, sessionId)
1213
+ // ⚠️ 顺序是刻意的:先取 usage(它报告的是**上一份**包之后发生了什么),
1214
+ // 再把这一份包记成新快照 —— 从下一次请求起,它才是「上一份」。
1215
+ body.usage = publicUsage(auditBridge.usage(root, sessionId, session))
1216
+ if (body.context) auditBridge.note(root, sessionId, session, body.context)
1217
+ }
1078
1218
  sendJson(res, 200, body)
1079
1219
  return
1080
1220
  }
@@ -1101,6 +1241,11 @@ export function apply(ctx) {
1101
1241
  total: payload.total,
1102
1242
  withLinks: payload.mode === 'relevance' && kind === 'doc',
1103
1243
  }))
1244
+ // v0.15:走这条路的调用方(只要上下文、不要列表)同样会推进 Context Snapshot ——
1245
+ // 否则「上下文变了」这件事会漏记。**只在已记账的会话里**(同 recent 的闸门)。
1246
+ if (sessionId && feedbackActive(sessionId)) {
1247
+ auditBridge.note(root, sessionId, sessionOf(webCtx, sessionId), context)
1248
+ }
1104
1249
  sendJson(res, 200, { ok: true, root, mode: payload.mode, topic: payload.topic, context })
1105
1250
  return
1106
1251
  }
@@ -1166,7 +1311,9 @@ export function apply(ctx) {
1166
1311
  // 两条路互不依赖:没有 tools 服务时,浏览器那半边照常工作。
1167
1312
  ctx.inject(['tools'], (toolCtx) => {
1168
1313
  toolCtx.effect(
1169
- () => registerKnitDocsTool(toolCtx, scan, readDocument, buildContextFor),
1314
+ // v0.15:多注入一个 `auditBridge` —— `knit_docs` 的 `audit: true` 走它拿
1315
+ // 「上一份包之后发生了什么」,并把这次交出的包记成新快照。
1316
+ () => registerKnitDocsTool(toolCtx, scan, readDocument, buildContextFor, auditBridge),
1170
1317
  'dsh-knit: knit_docs tool',
1171
1318
  )
1172
1319
  console.log(`[${name}] agent tool ready: knit_docs`)
package/src/host/tool.js CHANGED
@@ -107,6 +107,15 @@ const PARAMETERS = {
107
107
  description: `How many documents to consider (1-${MAX_LIMIT}, default ${DEFAULT_LIMIT}). `
108
108
  + 'They are grouped into the context tiers, not returned as one flat list.',
109
109
  },
110
+ // v0.15:可选的「使用情况」审计。**默认 false** —— 不传它时这次调用的
111
+ // 入参与返回值与 v0.14 逐字一致,老调用方一个字都不用改。
112
+ audit: {
113
+ type: 'boolean',
114
+ description: 'Set true to append a one-line usage summary of the PREVIOUS context pack: '
115
+ + 'whether its primary document has been read since, how many supporting documents were read, '
116
+ + 'and how many reads fell outside the pack. Counts only — no scores, no confidence. '
117
+ + 'Default false.',
118
+ },
110
119
  },
111
120
  }
112
121
 
@@ -196,6 +205,10 @@ const OUTPUT_SCHEMA = {
196
205
  },
197
206
  required: ['matched', 'total'],
198
207
  },
208
+ // v0.15:**可选**的一行「使用情况」(只有 `audit: true` 时才有)。
209
+ // 它说的全是计数与事实 —— 没有分数、没有百分比、没有置信度、没有 trajectory。
210
+ // 不传 `audit` 时这个字段根本不出现(而不是给个空串)。
211
+ usage: { type: 'string' },
199
212
  // 时间序(对话内容还不足,退回一列「最近改动的」)走这条。**形状比三层窄** ——
200
213
  // 没有命中词,就没有 `source` / `reason` 可给,不编造。只有 time 模式有。
201
214
  docs: {
@@ -438,6 +451,10 @@ export function renderToolText(value, readSnippet) {
438
451
  if (related.length > 0) {
439
452
  out.push('', 'Related (background — do not start here):', ...lines(related))
440
453
  }
454
+ // v0.15:可选的「使用情况」一行。**只有 `audit: true` 时 `execute` 才会填它**,
455
+ // 所以默认调用的输出与 v0.14 逐字一致。
456
+ const usage = (value && typeof value.usage === 'string') ? value.usage : ''
457
+ if (usage) out.push('', usage)
441
458
  return out.join('\n')
442
459
  }
443
460
 
@@ -462,6 +479,29 @@ function whyText(reason) {
462
479
  }
463
480
  }
464
481
 
482
+ /**
483
+ * 取「上一份 Context Pack 之后发生了什么」的一行摘要(v0.15)。
484
+ *
485
+ * `audit` 是**注入**进来的桥(宿主侧 `feedback.js` 的封装),工具自己不认识 feedback ——
486
+ * 与 `scan` / `read` / `contextFor` 同样的理由:一层做一件事,且避免 index.js ↔ tool.js 循环 import。
487
+ * 桥没给、桥抛了、桥返回了非字符串:一律当「没有可说的」,返回空串。
488
+ *
489
+ * @param {object} [audit] - `{summary(root, sessionId, session), note(root, sessionId, session, pack)}`
490
+ * @param {string} root - 工作区根
491
+ * @param {string} sessionId - 会话 id
492
+ * @param {object} session - 宿主会话
493
+ * @returns {string} 一行摘要或空串
494
+ */
495
+ function auditSummary(audit, root, sessionId, session) {
496
+ if (!audit || typeof audit.summary !== 'function' || !sessionId) return ''
497
+ try {
498
+ const line = audit.summary(root, sessionId, session)
499
+ return typeof line === 'string' ? line : ''
500
+ } catch {
501
+ return ''
502
+ }
503
+ }
504
+
465
505
  /**
466
506
  * 造出 `knit_docs` 的 `ToolDefinition`。
467
507
  *
@@ -475,9 +515,12 @@ function whyText(reason) {
475
515
  * `contextFor(root, {ranked, topic, task, total})` → Context Pack。
476
516
  * **同样注入**(v0.14):装配规则长在 `context.js` 里,工具只负责投影。
477
517
  * 不给就退化成 v0.13 的平铺列表 —— 但那只是兜底,正常路径 always 会传。
518
+ * @param {object} [audit] - Context Feedback 的桥(v0.15,**可选**):
519
+ * `{ summary(root, sessionId, session) → string, note(root, sessionId, session, pack) → void }`。
520
+ * 不给就完全没有审计能力 —— 工具的入参与返回值与 v0.14 逐字一致。
478
521
  * @returns {object} 工具定义
479
522
  */
480
- export function knitDocsDefinition(scan, read, contextFor) {
523
+ export function knitDocsDefinition(scan, read, contextFor, audit) {
481
524
  /**
482
525
  * 给一篇文档抽命中段落。
483
526
  *
@@ -524,6 +567,8 @@ export function knitDocsDefinition(scan, read, contextFor) {
524
567
 
525
568
  const query = typeof (args && args.query) === 'string' ? args.query.trim() : ''
526
569
  const limit = clampLimit(args && args.limit)
570
+ // v0.15:审计是**显式**的(默认 false)。不传它就完全不走 feedback 那条路。
571
+ const auditRequested = !!(args && args.audit === true)
527
572
 
528
573
  const payload = await scan(root, limit, {
529
574
  session,
@@ -605,6 +650,19 @@ export function knitDocsDefinition(scan, read, contextFor) {
605
650
  return snippet ? { ...item, snippet } : item
606
651
  }))
607
652
 
653
+ // ── v0.15 · Context Feedback ──────────────────────────────────────
654
+ // 顺序是刻意的:先取「**上一份**包之后发生了什么」(usage 是回过头看的),
655
+ // 再把这一份包记成新的 Context Snapshot —— 从下一次调用起,它才是「上一份」。
656
+ // 两步都只是记账,任何失败都只让摘要少一行,绝不让整次工具调用失败。
657
+ const usage = auditRequested ? auditSummary(audit, root, sessionId, session) : ''
658
+ if (auditRequested && audit && typeof audit.note === 'function' && sessionId) {
659
+ try {
660
+ audit.note(root, sessionId, session, pack)
661
+ } catch {
662
+ // 记账失败不影响排序结果 —— 这是「Knit 坏了也不许影响 Agent」那条纪律
663
+ }
664
+ }
665
+
608
666
  return {
609
667
  mode: 'relevance',
610
668
  topic: typeof pack.topic === 'string' ? pack.topic : '',
@@ -619,6 +677,8 @@ export function knitDocsDefinition(scan, read, contextFor) {
619
677
  primary: await withSnippets(pack.primary || []),
620
678
  supporting: await withSnippets(pack.supporting || []),
621
679
  related: await withSnippets(pack.related || []),
680
+ // 只有 `audit: true` 且真的取到摘要时才有这个字段(否则连键都不出现)
681
+ ...(usage ? { usage } : {}),
622
682
  }
623
683
  },
624
684
  }
@@ -633,8 +693,9 @@ export function knitDocsDefinition(scan, read, contextFor) {
633
693
  * @param {Function} scan - 宿主的扫描函数
634
694
  * @param {Function} [read] - 宿主的单篇读取函数(抽命中段落用;可选)
635
695
  * @param {Function} [contextFor] - 宿主的上下文装配函数(v0.14;可选)
696
+ * @param {object} [audit] - Context Feedback 的桥(v0.15;可选)
636
697
  * @returns {() => void} 注销函数
637
698
  */
638
- export function registerKnitDocsTool(ctx, scan, read, contextFor) {
639
- return ctx.tools.register(knitDocsDefinition(scan, read, contextFor))
699
+ export function registerKnitDocsTool(ctx, scan, read, contextFor, audit) {
700
+ return ctx.tools.register(knitDocsDefinition(scan, read, contextFor, audit))
640
701
  }
@@ -1927,3 +1927,102 @@ test('样式:组与组之间只靠 16px 空间(不再画横线),序号
1927
1927
  assert.match(source, /\.knit-num\{grid-column:1;font-size:10\.5px;line-height:19\.6px;/)
1928
1928
  assert.match(source, /\.knit-sum\{font-size:12px;line-height:19px;/)
1929
1929
  })
1930
+
1931
+ /* ── v0.15「使用情况」 ───────────────────────────────────────────────
1932
+ 三条纪律要一起守住:① **默认关**(没打开就一个事件都不读);
1933
+ ② 打开后请求带 `usage=1`(那是宿主侧的开闸信号,不是可选参数);
1934
+ ③ 显示的只有**事实**:读了几次、落在哪一层、上下文换过几回 ——
1935
+ **没有分数、没有百分比、没有评分条**(用户明确要求过)。 */
1936
+
1937
+ /** 一份带 usage 的宿主载荷:先看的那篇(docs/algo.md)已被读。 */
1938
+ function usagePayload() {
1939
+ return contextPayload({
1940
+ usage: {
1941
+ at: 1_700_000_000_000,
1942
+ stats: {
1943
+ reads: 7,
1944
+ distinct: 3,
1945
+ outside: 2,
1946
+ outsideReads: ['knit/src/host/index.js'],
1947
+ firstReadTier: 'primary',
1948
+ firstReadRel: 'docs/algo.md',
1949
+ firstReadAt: 1,
1950
+ primaryRel: 'docs/algo.md',
1951
+ primaryFollowThrough: true,
1952
+ byTier: {
1953
+ primary: { total: 1, read: 1 },
1954
+ supporting: { total: 2, read: 1 },
1955
+ related: { total: 1, read: 0 },
1956
+ },
1957
+ supportingCoverage: 0.5,
1958
+ churn: { snapshots: 2, deltas: 2, retained: 2, appeared: 1, disappeared: 0, moved: 0, taskChanged: 0 },
1959
+ },
1960
+ delta: { appeared: ['docs/eval.md'], disappeared: [], moved: [], taskChanged: false },
1961
+ },
1962
+ })
1963
+ }
1964
+
1965
+ test('使用情况:默认关 —— 请求里没有 usage=1,DOM 里也没有那一行', async () => {
1966
+ const { calls } = installFetch(() => usagePayload())
1967
+ const { KnitBody } = loadClientModule().exports.__test
1968
+ harness.reset()
1969
+ harness.seed(['', 'relevance'])
1970
+ const render = () => harness.render(h(KnitBody, { sessionId: 's1' }))
1971
+ let nodes = render()
1972
+ await harness.flush()
1973
+ nodes = render()
1974
+ await harness.flush()
1975
+ nodes = render()
1976
+
1977
+ assert.ok(!calls.some((url) => url.includes('usage=1')), '默认关:一个会话事件都不该被读')
1978
+ assert.equal(byExactClass(nodes, 'knit-usage').length, 0, '默认关:不显示那一行')
1979
+ })
1980
+
1981
+ test('使用情况:打开后请求带 usage=1,那一行只报事实(没有分数 / 百分比)', async () => {
1982
+ const { calls } = installFetch(() => usagePayload())
1983
+ const { KnitBody } = loadClientModule().exports.__test
1984
+ harness.reset()
1985
+ harness.seed(['', 'relevance'])
1986
+ const render = () => harness.render(h(KnitBody, { sessionId: 's1' }))
1987
+ let nodes = render()
1988
+ await harness.flush()
1989
+ nodes = render()
1990
+ await harness.flush()
1991
+ nodes = render()
1992
+
1993
+ const toggle = byExactClass(nodes, 'knit-btn').find((node) => textOf(node) === '使用情况')
1994
+ assert.ok(toggle, '头部必须有「使用情况」按钮')
1995
+ assert.equal(toggle.props['aria-pressed'], false, '默认关')
1996
+ toggle.props.onClick()
1997
+ await harness.flush()
1998
+ nodes = render()
1999
+ await harness.flush()
2000
+ nodes = render()
2001
+
2002
+ assert.ok(calls.some((url) => url.includes('usage=1')), '打开后必须带 usage=1')
2003
+ const line = byExactClass(nodes, 'knit-usage')[0]
2004
+ assert.ok(line, '打开后必须出现那一行')
2005
+ const text = textOf(line)
2006
+ assert.match(text, /已读/, '先看的那篇被读了要如实说出来')
2007
+ assert.match(text, /辅助 1\/2/)
2008
+ assert.match(text, /读了 7 次/)
2009
+ assert.match(text, /包外 2 篇/)
2010
+ assert.match(text, /上下文换过 2 次/)
2011
+ assert.ok(!text.includes('%'), '不许有百分比')
2012
+ assert.ok(!/评分|置信|分数/.test(text), '不许有评分 / 置信度这类词')
2013
+ })
2014
+
2015
+ test('样式:使用情况那一行是弱化文字 —— 没有卡片 / 进度条 / 品牌色', async () => {
2016
+ const { readFileSync } = await import('node:fs')
2017
+ const { fileURLToPath } = await import('node:url')
2018
+ const source = readFileSync(
2019
+ fileURLToPath(new URL('../src/client/client.js', import.meta.url)),
2020
+ 'utf8',
2021
+ )
2022
+ assert.match(source, /\.knit-usage\{[^}]*font-size:10\.5px/)
2023
+ assert.ok(!/\.knit-usage\{[^}]*background/.test(source), '不画卡片底色')
2024
+ assert.ok(!/\.knit-usage\{[^}]*knit-accent/.test(source), '不用品牌色')
2025
+ assert.ok(!/\.knit-usage\{[^}]*width:\s*\d/.test(source), '不是进度条')
2026
+ // 开关本身也不许染色
2027
+ assert.ok(!/\.knit-btn\.active\{[^}]*knit-accent/.test(source), '开关的选中态走中性灰')
2028
+ })