dsh-knit 0.14.0 → 0.16.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
 
@@ -937,6 +943,26 @@ export function parseRange(header, size) {
937
943
  return { start, end }
938
944
  }
939
945
 
946
+ /**
947
+ * 从一个宿主会话对象解析工作区根。
948
+ *
949
+ * v0.16 起 `session/event` 的订阅回调里**只有 session 对象**(没有注入过的 webCtx),
950
+ * 所以这段逻辑必须能独立使用:面板路由与记账回调共用它,保证「算列表用的根」与
951
+ * 「归一化读路径用的根」永远是同一个 —— 否则同一次读会被一边算作包内、
952
+ * 一边算作包外(AGENTS.md §8.10 踩过这个坑)。
953
+ * @param {object} session - 宿主会话(可为空)
954
+ * @returns {string} 绝对路径根
955
+ */
956
+ function rootOfSession(session) {
957
+ let root = ''
958
+ try {
959
+ if (session && session.header && typeof session.header.cwd === 'string') root = session.header.cwd
960
+ } catch { /* 取不到 cwd 就走兜底根 */ }
961
+ if (!root) root = process.cwd()
962
+ if (root.startsWith('~')) root = join(homedir(), root.slice(1))
963
+ return resolve(root)
964
+ }
965
+
940
966
  /**
941
967
  * 解析一个会话的工作区根。
942
968
  * @param {object} webCtx - 注入了 sessions 的上下文
@@ -944,16 +970,13 @@ export function parseRange(header, size) {
944
970
  * @returns {string} 绝对路径根
945
971
  */
946
972
  function workspaceRootOf(webCtx, sessionId) {
947
- let root = ''
973
+ let session
948
974
  try {
949
- const session = sessionId && typeof webCtx.sessions.get === 'function'
975
+ session = sessionId && typeof webCtx.sessions.get === 'function'
950
976
  ? webCtx.sessions.get(sessionId)
951
977
  : undefined
952
- if (session && session.header && typeof session.header.cwd === 'string') root = session.header.cwd
953
978
  } catch { /* 会话查不到就走兜底根 */ }
954
- if (!root) root = process.cwd()
955
- if (root.startsWith('~')) root = join(homedir(), root.slice(1))
956
- return resolve(root)
979
+ return rootOfSession(session)
957
980
  }
958
981
 
959
982
  /**
@@ -1041,12 +1064,137 @@ function sendMedia(req, res, info) {
1041
1064
  stream.pipe(res)
1042
1065
  }
1043
1066
 
1067
+ /* ── v0.16 · Context Feedback 的宿主侧封装 ────────────────────────────
1068
+ *
1069
+ * 这一层只做三件事:
1070
+ * 1. **订阅**宿主的 `session/event`,把真实发生过的 `read` 一条条喂给 feedback store;
1071
+ * 2. 把刚交出去的 Context Pack 记成 Context Snapshot(带 `epochId`);
1072
+ * 3. 给面板与 `knit_docs` 提供「**上一份**包之后发生了什么」。
1073
+ *
1074
+ * ⚠️ v0.16 起**不再**从 `session.snapshotEvents()` 拉事件:那个 API 已被 DSH 标记
1075
+ * deprecated(「new production calls are prohibited」),而且它会把这个会话从父会话
1076
+ * fork 继承来的前缀事件也算进来。代价是:订阅之前发生过的事件不回溯 —— 宁可少记,
1077
+ * 也不去猜一段没法按当时上下文归因的历史。
1078
+ *
1079
+ * 记账只在**被显式打开**的会话里发生(面板的「使用情况」开关,或 `knit_docs` 的
1080
+ * `audit: true`)—— 默认一条事件的处理成本就是一次 Map 查找。
1081
+ * 所有入口都 try/catch:记账坏了不许影响面板与工具(规格 §33 的降级纪律)。
1082
+ */
1083
+
1084
+ /** 进程内唯一的 feedback store(按会话分片,会话数与篇数都有硬上限)。 */
1085
+ const feedbackStore = createStore()
1086
+
1087
+ /**
1088
+ * 订阅宿主的会话事件流,把真实的读记进 store。
1089
+ *
1090
+ * `{ global: true }` 是**必需**的:`session/event` 按 scope 过滤派发,而这个插件挂在
1091
+ * 根上下文上、要看的却是各 agent scope 里的会话(宿主自己的 `invariant.js` 也这么订)。
1092
+ *
1093
+ * 三道闸门,顺序即开销顺序:**没记账的会话,一条事件只花一次 Map 查找**就返回。
1094
+ * 任何异常一律咽掉 —— 记账坏了绝不许影响宿主。
1095
+ * @param {object} session - 宿主会话
1096
+ * @param {object} event - 会话事件(`tool/call` / `tool/result` / 其它)
1097
+ * @returns {void}
1098
+ */
1099
+ function onSessionEvent(session, event) {
1100
+ try {
1101
+ const sessionId = session && typeof session.id === 'string' ? session.id : ''
1102
+ if (!sessionId || !event) return
1103
+ if (!isAudited(feedbackStore, sessionId)) return
1104
+ ingestEvents(feedbackStore, sessionId, [event], { root: rootOfSession(session) })
1105
+ } catch { /* 记账坏了不许影响宿主 */ }
1106
+ }
1107
+
1108
+ /**
1109
+ * 打开某个会话的记账(面板的「使用情况」开关走它)。
1110
+ * @param {string} sessionId - 会话 id
1111
+ * @returns {boolean} 是否成功
1112
+ */
1113
+ export function activateFeedback(sessionId) {
1114
+ return activateAudit(feedbackStore, sessionId)
1115
+ }
1116
+
1117
+ /**
1118
+ * 这个会话在记账吗。
1119
+ * @param {string} sessionId - 会话 id
1120
+ * @returns {boolean} 是否记账
1121
+ */
1122
+ export function feedbackActive(sessionId) {
1123
+ return isAudited(feedbackStore, sessionId)
1124
+ }
1125
+
1126
+ /**
1127
+ * 线路上的紧凑使用情况:面板只需要**计数**与最近一次变化,不需要 200 条明细。
1128
+ * @param {object|null} usage - `usageFor()` 的结果
1129
+ * @param {number} [limit] - 明细最多带几条
1130
+ * @returns {object|null} 紧凑视图
1131
+ */
1132
+ export function publicUsage(usage, limit = 20) {
1133
+ if (!usage || !usage.stats) return null
1134
+ return {
1135
+ at: usage.at,
1136
+ epochId: usage.epochId,
1137
+ stats: { ...usage.stats, outsideReads: usage.stats.outsideReads.slice(0, limit) },
1138
+ delta: usage.delta ? {
1139
+ appeared: usage.delta.appeared.slice(0, limit),
1140
+ disappeared: usage.delta.disappeared.slice(0, limit),
1141
+ moved: usage.delta.moved.slice(0, limit),
1142
+ taskChanged: !!usage.delta.taskChanged,
1143
+ } : null,
1144
+ }
1145
+ }
1146
+
1147
+ /**
1148
+ * 注入给 `knit_docs` 的桥 —— 工具不认识 `feedback.js`,只认识这两个方法
1149
+ * (与 `scan` / `read` / `contextFor` 同样的注入理由)。
1150
+ *
1151
+ * ⚠️ `summary()` 必须在 `note()` **之前**调用:它报告的是**上一份**包的用法。
1152
+ * v0.16 起这个桥**不再收** root 与 session:读证据由订阅那条路进 store,
1153
+ * 交包只是记一份快照(`seq` 用 store 自己的事件水位)。
1154
+ */
1155
+ const auditBridge = {
1156
+ usage(sessionId) {
1157
+ try {
1158
+ if (!sessionId) return null
1159
+ return usageFor(feedbackStore, sessionId)
1160
+ } catch {
1161
+ return null
1162
+ }
1163
+ },
1164
+ summary(sessionId) {
1165
+ try {
1166
+ if (!sessionId) return ''
1167
+ return getAuditSummary(usageFor(feedbackStore, sessionId))
1168
+ } catch {
1169
+ return ''
1170
+ }
1171
+ },
1172
+ note(sessionId, pack) {
1173
+ try {
1174
+ if (!sessionId || !pack) return null
1175
+ // 走到这里说明记账是**显式**的(面板带了 `usage=1`,或 agent 传了 `audit: true`
1176
+ // 且 `tool.js` 只在那一刻调 note)—— 所以在这里开闸是安全的。
1177
+ activateAudit(feedbackStore, sessionId)
1178
+ // 不传 `seq`:noteSnapshot 用会话当前的**事件水位**,也就是「交这份包时
1179
+ // 已经发生到第几个事件」—— seq ≤ 它的读才算在这份包里。
1180
+ return noteSnapshot(feedbackStore, sessionId, pack, { at: Date.now() })
1181
+ } catch {
1182
+ return null
1183
+ }
1184
+ },
1185
+ }
1186
+
1044
1187
  /**
1045
1188
  * 宿主插件体:等 webServer / sessions 到位后挂只读路由。
1046
1189
  * @param {import('@deepseek-ai/cordis').Context} ctx - 宿主根上下文
1047
1190
  * @returns {void}
1048
1191
  */
1049
1192
  export function apply(ctx) {
1193
+ // v0.16:订阅会话事件流 —— 这是 Knit 唯一的读证据来源。
1194
+ // ⚠️ 注册在这里,而不是 `inject(['webServer','sessions'])` 的回调里:
1195
+ // `knit_docs` 的 `audit: true` 也能打开记账,没有 webServer 的环境照样要记。
1196
+ ctx.on('session/event', onSessionEvent, { global: true })
1197
+
1050
1198
  ctx.inject(['webServer', 'sessions'], (webCtx) => {
1051
1199
  const handler = async (req, res) => {
1052
1200
  if (!isLoopback(req.socket?.remoteAddress)) {
@@ -1075,6 +1223,15 @@ export function apply(ctx) {
1075
1223
  // v0.14:相关模式下顺带给出任务上下文分层。
1076
1224
  // ⚠️ 带上 `context` 是**可选**的(老客户端忽略它),而 `docs` 一字未动。
1077
1225
  body.context = await contextPayload(root, payload, sort, kind)
1226
+ // v0.15:面板把「使用情况」开关打开后,请求会带 `usage=1` —— 那一刻开始记账。
1227
+ // ⚠️ 默认(不带这个参数且本会话从未打开过)**一个字节都不记**。
1228
+ if (sessionId && url.searchParams.get('usage') === '1') activateFeedback(sessionId)
1229
+ if (sessionId && feedbackActive(sessionId)) {
1230
+ // ⚠️ 顺序是刻意的:先取 usage(它报告的是**上一份**包之后发生了什么),
1231
+ // 再把这一份包记成新快照 —— 从下一次请求起,它才是「上一份」。
1232
+ body.usage = publicUsage(auditBridge.usage(sessionId))
1233
+ if (body.context) auditBridge.note(sessionId, body.context)
1234
+ }
1078
1235
  sendJson(res, 200, body)
1079
1236
  return
1080
1237
  }
@@ -1101,6 +1258,11 @@ export function apply(ctx) {
1101
1258
  total: payload.total,
1102
1259
  withLinks: payload.mode === 'relevance' && kind === 'doc',
1103
1260
  }))
1261
+ // v0.15:走这条路的调用方(只要上下文、不要列表)同样会推进 Context Snapshot ——
1262
+ // 否则「上下文变了」这件事会漏记。**只在已记账的会话里**(同 recent 的闸门)。
1263
+ if (sessionId && feedbackActive(sessionId)) {
1264
+ auditBridge.note(sessionId, context)
1265
+ }
1104
1266
  sendJson(res, 200, { ok: true, root, mode: payload.mode, topic: payload.topic, context })
1105
1267
  return
1106
1268
  }
@@ -1166,7 +1328,9 @@ export function apply(ctx) {
1166
1328
  // 两条路互不依赖:没有 tools 服务时,浏览器那半边照常工作。
1167
1329
  ctx.inject(['tools'], (toolCtx) => {
1168
1330
  toolCtx.effect(
1169
- () => registerKnitDocsTool(toolCtx, scan, readDocument, buildContextFor),
1331
+ // v0.15:多注入一个 `auditBridge` —— `knit_docs` 的 `audit: true` 走它拿
1332
+ // 「上一份包之后发生了什么」,并把这次交出的包记成新快照。
1333
+ () => registerKnitDocsTool(toolCtx, scan, readDocument, buildContextFor, auditBridge),
1170
1334
  'dsh-knit: knit_docs tool',
1171
1335
  )
1172
1336
  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,27 @@ 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(sessionId), note(sessionId, pack)}`
490
+ * @param {string} sessionId - 会话 id
491
+ * @returns {string} 一行摘要或空串
492
+ */
493
+ function auditSummary(audit, sessionId) {
494
+ if (!audit || typeof audit.summary !== 'function' || !sessionId) return ''
495
+ try {
496
+ const line = audit.summary(sessionId)
497
+ return typeof line === 'string' ? line : ''
498
+ } catch {
499
+ return ''
500
+ }
501
+ }
502
+
465
503
  /**
466
504
  * 造出 `knit_docs` 的 `ToolDefinition`。
467
505
  *
@@ -475,9 +513,13 @@ function whyText(reason) {
475
513
  * `contextFor(root, {ranked, topic, task, total})` → Context Pack。
476
514
  * **同样注入**(v0.14):装配规则长在 `context.js` 里,工具只负责投影。
477
515
  * 不给就退化成 v0.13 的平铺列表 —— 但那只是兜底,正常路径 always 会传。
516
+ * @param {object} [audit] - Context Feedback 的桥(v0.16,**可选**):
517
+ * `{ summary(sessionId) → string, note(sessionId, pack) → void }`。
518
+ * 桥不再需要工作区根与会话对象:读证据由宿主的 `session/event` 订阅进 store。
519
+ * 不给就完全没有审计能力 —— 工具的入参与返回值与 v0.14 逐字一致。
478
520
  * @returns {object} 工具定义
479
521
  */
480
- export function knitDocsDefinition(scan, read, contextFor) {
522
+ export function knitDocsDefinition(scan, read, contextFor, audit) {
481
523
  /**
482
524
  * 给一篇文档抽命中段落。
483
525
  *
@@ -524,6 +566,8 @@ export function knitDocsDefinition(scan, read, contextFor) {
524
566
 
525
567
  const query = typeof (args && args.query) === 'string' ? args.query.trim() : ''
526
568
  const limit = clampLimit(args && args.limit)
569
+ // v0.15:审计是**显式**的(默认 false)。不传它就完全不走 feedback 那条路。
570
+ const auditRequested = !!(args && args.audit === true)
527
571
 
528
572
  const payload = await scan(root, limit, {
529
573
  session,
@@ -605,6 +649,19 @@ export function knitDocsDefinition(scan, read, contextFor) {
605
649
  return snippet ? { ...item, snippet } : item
606
650
  }))
607
651
 
652
+ // ── v0.15 · Context Feedback ──────────────────────────────────────
653
+ // 顺序是刻意的:先取「**上一份**包之后发生了什么」(usage 是回过头看的),
654
+ // 再把这一份包记成新的 Context Snapshot —— 从下一次调用起,它才是「上一份」。
655
+ // 两步都只是记账,任何失败都只让摘要少一行,绝不让整次工具调用失败。
656
+ const usage = auditRequested ? auditSummary(audit, sessionId) : ''
657
+ if (auditRequested && audit && typeof audit.note === 'function' && sessionId) {
658
+ try {
659
+ audit.note(sessionId, pack)
660
+ } catch {
661
+ // 记账失败不影响排序结果 —— 这是「Knit 坏了也不许影响 Agent」那条纪律
662
+ }
663
+ }
664
+
608
665
  return {
609
666
  mode: 'relevance',
610
667
  topic: typeof pack.topic === 'string' ? pack.topic : '',
@@ -619,6 +676,8 @@ export function knitDocsDefinition(scan, read, contextFor) {
619
676
  primary: await withSnippets(pack.primary || []),
620
677
  supporting: await withSnippets(pack.supporting || []),
621
678
  related: await withSnippets(pack.related || []),
679
+ // 只有 `audit: true` 且真的取到摘要时才有这个字段(否则连键都不出现)
680
+ ...(usage ? { usage } : {}),
622
681
  }
623
682
  },
624
683
  }
@@ -633,8 +692,9 @@ export function knitDocsDefinition(scan, read, contextFor) {
633
692
  * @param {Function} scan - 宿主的扫描函数
634
693
  * @param {Function} [read] - 宿主的单篇读取函数(抽命中段落用;可选)
635
694
  * @param {Function} [contextFor] - 宿主的上下文装配函数(v0.14;可选)
695
+ * @param {object} [audit] - Context Feedback 的桥(v0.15;可选)
636
696
  * @returns {() => void} 注销函数
637
697
  */
638
- export function registerKnitDocsTool(ctx, scan, read, contextFor) {
639
- return ctx.tools.register(knitDocsDefinition(scan, read, contextFor))
698
+ export function registerKnitDocsTool(ctx, scan, read, contextFor, audit) {
699
+ return ctx.tools.register(knitDocsDefinition(scan, read, contextFor, audit))
640
700
  }