@restregular/dsh-memory 0.9.5 → 0.9.7

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.
@@ -0,0 +1,87 @@
1
+ /**
2
+ * 注入审计:每次摘要/召回评估都留一条结构化记录。
3
+ *
4
+ * 第一版不要求复杂 UI:记录放在内存环形缓冲里,provider 通过
5
+ * `attachInjectAudit()` 挂上,面板 `GET /memory/api/audit?session=` 读取。
6
+ * 不记录任何凭据/令牌;检索查询会先过凭据脱敏,再最多截到 200 字。
7
+ */
8
+
9
+ import { redactSecrets } from '../provider/secrets.js'
10
+
11
+
12
+
13
+
14
+
15
+
16
+
17
+
18
+
19
+
20
+
21
+
22
+
23
+
24
+
25
+
26
+
27
+
28
+
29
+                     
30
+
31
+
32
+
33
+
34
+
35
+
36
+
37
+
38
+
39
+         
40
+
41
+
42
+
43
+
44
+
45
+
46
+
47
+
48
+                          
49
+
50
+
51
+
52
+
53
+ const MAX_ENTRIES = 200
54
+
55
+ export class InjectAuditStore {
56
+ entries = []
57
+
58
+ record(entry ) {
59
+ this.entries.push(entry)
60
+ if (this.entries.length > MAX_ENTRIES) this.entries.splice(0, this.entries.length - MAX_ENTRIES)
61
+ }
62
+
63
+ /** 最新在前;可按会话过滤。 */
64
+ list(sessionId ) {
65
+ const list = sessionId === undefined
66
+ ? this.entries
67
+ : this.entries.filter((entry) => entry.sessionId === sessionId)
68
+ return [...list].reverse()
69
+ }
70
+
71
+ clear() {
72
+ this.entries = []
73
+ }
74
+ }
75
+
76
+ /** 查询文本里可能带用户内容:截断并折叠空白,不写凭据。 */
77
+ export function auditQuery(text ) {
78
+ if (typeof text !== 'string' || text.trim() === '') return undefined
79
+ return redactSecrets(text).replace(/\s+/g, ' ').trim().slice(0, 200)
80
+ }
81
+
82
+ export function auditBudget(budget , used ) {
83
+ return { budget, used, remaining: Math.max(0, budget - used) }
84
+ }
85
+
86
+
87
+ //# sourceURL=source/memory-inject/src/audit.ts
@@ -3,6 +3,12 @@
3
3
  *
4
4
  * 与逐轮召回的分工:召回按这一轮的问题找;摘要不按问题,按重要度 × 新鲜度
5
5
  * 挑几条,让模型一开始就知道有哪些旧结论可复用,而不是先搜一遍。
6
+ *
7
+ * 0.9.6 起,摘要不再静默截断:
8
+ * - 返回完整的候选/注入/省略统计与每条省略原因(top_k / budget / superseded / expired);
9
+ * - 被省略的正文会生成一段**独立的标签索引**,让模型知道哪些领域还有未展开的记忆;
10
+ * - 标签索引有自己的 token 预算与条数上限,不会反过来挤爆正文;
11
+ * - 退役(superseded)记录默认不进入摘要正文,也不生成索引。
6
12
  */
7
13
 
8
14
  import { estimateTokens } from '../provider/rerank.js'
@@ -12,6 +18,58 @@ const HEADER =
12
18
  '以下是本项目 / 全局已有的长期记忆摘要(按重要度挑出的前几条;' +
13
19
  '需要原文用 memory_search,删除用 memory_forget):'
14
20
 
21
+ const HINT_HEADER = '相关记忆索引(正文未注入):'
22
+ const HINT_FOOTER = '这些条目的正文尚未加载;遇到相关任务时,按标签或 ID 用 memory_search 取正文。'
23
+
24
+ /** 一条正文被省略的原因。统计口径互斥:每条记录只归入一个原因。 */
25
+
26
+
27
+
28
+
29
+
30
+                 
31
+
32
+
33
+
34
+
35
+
36
+
37
+
38
+
39
+
40
+
41
+
42
+
43
+
44
+
45
+
46
+
47
+
48
+
49
+
50
+
51
+
52
+
53
+
54
+
55
+
56
+                        
57
+
58
+                      
59
+
60
+               
61
+
62
+
63
+
64
+
65
+
66
+
67
+                    
68
+
69
+
70
+
71
+
72
+
15
73
  /** scope 的中文标签:global/项目/会话/自定义。 */
16
74
  export function digestScopeLabel(scope ) {
17
75
  if (scope === 'global') return '全局'
@@ -22,8 +80,10 @@ export function digestScopeLabel(scope ) {
22
80
 
23
81
  /**
24
82
  * 摘要排序:与淘汰规则同一套"新鲜度(30 天半衰期)× 重要度",并列时按作用域
25
- * 优先级(会话 > 项目 > 自定义 > 全局),最后按内容稳定排序 —— 同样的输入必须
26
- * 给出同样的摘要,否则两个注入实例的内容会对不上。
83
+ * 优先级(会话 > 项目 > 自定义 > 全局),再按 accessCount(弱辅助)、内容稳定排序 ——
84
+ * 同样的输入必须给出同样的摘要,否则两个注入实例的内容会对不上。
85
+ *
86
+ * accessCount 只在分数与作用域都相同时作为弱 tie-break,不能压过任务相关性。
27
87
  */
28
88
  export function rankForDigest(records , now = Date.now()) {
29
89
  const weight = (scope ) => {
@@ -32,34 +92,211 @@ export function rankForDigest(records , now = Date.now()
32
92
  if (scope === 'global') return 0
33
93
  return 1
34
94
  }
95
+ const score = (record ) =>
96
+ Math.pow(0.5, Math.max(0, now - record.updatedAt) / 86_400_000 / 30) * (0.1 + record.importance)
35
97
  return [...records].sort((a, b) => {
36
- const ra = Math.pow(0.5, Math.max(0, now - a.updatedAt) / 86_400_000 / 30) * (0.1 + a.importance)
37
- const rb = Math.pow(0.5, Math.max(0, now - b.updatedAt) / 86_400_000 / 30) * (0.1 + b.importance)
98
+ const ra = score(a)
99
+ const rb = score(b)
38
100
  if (rb !== ra) return rb - ra
39
101
  const wa = weight(a.scope)
40
102
  const wb = weight(b.scope)
41
103
  if (wa !== wb) return wb - wa
104
+ if ((b.accessCount ?? 0) !== (a.accessCount ?? 0)) return (b.accessCount ?? 0) - (a.accessCount ?? 0)
42
105
  return a.content.localeCompare(b.content)
43
106
  })
44
107
  }
45
108
 
46
- /** 渲染摘要块;没有记录返回 null,每条截 160 字,在预算内贪心填充。 */
47
- export function renderDigestBlock(
48
- records ,
49
- cfg ,
50
- ) {
109
+ /** 被任何一条记录 supersedes 指向的记录 id(只读扫描,不修改存储)。 */
110
+ export function supersededIds(records ) {
111
+ const ids = new Set ()
112
+ for (const record of records) {
113
+ if (typeof record.supersedes === 'string' && record.supersedes.length > 0) ids.add(record.supersedes)
114
+ }
115
+ return ids
116
+ }
117
+
118
+ function tagsOf(record ) {
119
+ return (record.tags ?? [])
120
+ .map((tag) => String(tag).trim())
121
+ .filter((tag) => tag.length > 0)
122
+ }
123
+
124
+ /** 标签索引的一行:ID / 主题标签 / 类型 / 作用域。不复制正文。 */
125
+ export function digestHintLine(record ) {
126
+ const tags = tagsOf(record).slice(0, 4)
127
+ const topic = tags.length > 0 ? tags.join('/') : record.content.replace(/\s+/g, ' ').trim().slice(0, 30)
128
+ return `- \`${record.id.slice(0, 8)}\` · ${topic} · ${record.kind} · ${digestScopeLabel(record.scope)}`
129
+ }
130
+
131
+ /** 标签索引的主题优先词:操作流程/发布/部署/凭据。 */
132
+ const OPERATIONAL_TAGS = new Set([
133
+ 'release', 'publish', 'deploy', 'deployment', 'credentials', 'credential',
134
+ 'npm', 'git', 'github', 'push', 'rollback', '发布', '推送', '部署', '凭据',
135
+ ])
136
+
137
+ /**
138
+ * 被截断记录的索引优先级:mandatory/pinned 最前,其次是操作型标签/类型,
139
+ * 最后才按原摘要排名。避免索引预算被一堆普通事实占满,真正需要的发布流程却进不来。
140
+ */
141
+ function hintPriority(record ) {
142
+ const tags = tagsOf(record).map((tag) => tag.toLowerCase())
143
+ let score = 0
144
+ if (tags.some((tag) => tag === 'mandatory' || tag === 'pinned' || tag === '必含' || tag === '强制')) score += 100
145
+ if (tags.some((tag) => OPERATIONAL_TAGS.has(tag) || tag.startsWith('phase:'))) score += 60
146
+ if (record.kind === 'procedure' || record.kind === 'rule') score += 20
147
+ return score
148
+ }
149
+
150
+ function prioritizeHints(records ) {
151
+ return [...records]
152
+ .map((record, index) => ({ record, index, priority: hintPriority(record) }))
153
+ .sort((a, b) => b.priority - a.priority || a.index - b.index)
154
+ .map((entry) => entry.record)
155
+ }
156
+
157
+ /** 生成被省略记录的标签索引;预算/条数独立于正文。 */
158
+ function renderHintIndex(omitted , cfg )
159
+
160
+
161
+
162
+
163
+
164
+
165
+ {
166
+ if (omitted.length === 0) {
167
+ return { text: null, tokens: 0, injected: 0, omittedTopK: 0, omittedBudget: 0, injectedIds: [] }
168
+ }
169
+ let tokens = estimateTokens(HINT_HEADER) + 4
170
+ const lines = []
171
+ const injectedIds = []
172
+ let omittedTopK = 0
173
+ let omittedBudget = 0
174
+ for (const record of prioritizeHints(omitted)) {
175
+ if (lines.length >= cfg.hintMaxItems) { omittedTopK += 1; continue }
176
+ const line = digestHintLine(record)
177
+ const cost = estimateTokens(line) + 1
178
+ if (tokens + cost > cfg.hintBudget) { omittedBudget += 1; continue }
179
+ lines.push(line)
180
+ injectedIds.push(record.id)
181
+ tokens += cost
182
+ }
183
+ if (lines.length === 0) {
184
+ return { text: null, tokens: 0, injected: 0, omittedTopK, omittedBudget, injectedIds }
185
+ }
186
+ let text = `${HINT_HEADER}\n${lines.join('\n')}\n${HINT_FOOTER}`
187
+ const extra = []
188
+ if (omittedTopK > 0) extra.push(`条数上限 ${omittedTopK}`)
189
+ if (omittedBudget > 0) extra.push(`预算 ${omittedBudget}`)
190
+ if (extra.length > 0) text += `\n(另有 ${extra.join(' / ')} 条索引未展示)`
191
+ return { text, tokens, injected: lines.length, omittedTopK, omittedBudget, injectedIds }
192
+ }
193
+
194
+ /**
195
+ * 摘要的完整计划:正文 + 截断统计 + 标签索引。
196
+ *
197
+ * 统计口径:先按退役/过期过滤,再按排序依次尝试注入;`selected` 以外的记录
198
+ * 只会归入 `top_k`、`budget`、`superseded`、`expired` 之一。
199
+ */
200
+ export function renderDigest(records , cfg , now = Date.now()) {
51
201
  if (records.length === 0) return null
202
+
203
+ const retired = supersededIds(records)
204
+ const active = []
205
+ const omitted = []
206
+ let omittedSuperseded = 0
207
+ let omittedExpired = 0
208
+ for (const record of records) {
209
+ if (retired.has(record.id)) {
210
+ omittedSuperseded += 1
211
+ omitted.push({ id: record.id, reason: 'superseded', kind: record.kind, tags: tagsOf(record) })
212
+ continue
213
+ }
214
+ if (record.expiredAt !== undefined && record.expiredAt < now) {
215
+ omittedExpired += 1
216
+ omitted.push({ id: record.id, reason: 'expired', kind: record.kind, tags: tagsOf(record) })
217
+ continue
218
+ }
219
+ active.push(record)
220
+ }
221
+
222
+ const ranked = rankForDigest(active, now)
223
+ const selected = []
224
+ const hintCandidates = []
52
225
  let tokens = estimateTokens(HEADER) + 4
53
- const lines = []
54
- for (const record of rankForDigest(records).slice(0, cfg.topK)) {
226
+ let omittedTopK = 0
227
+ let omittedBudget = 0
228
+ let budgetExhausted = false
229
+ for (const record of ranked) {
230
+ if (selected.length >= cfg.topK) {
231
+ omittedTopK += 1
232
+ hintCandidates.push(record)
233
+ omitted.push({ id: record.id, reason: 'top_k', kind: record.kind, tags: tagsOf(record) })
234
+ continue
235
+ }
236
+ if (budgetExhausted) {
237
+ omittedBudget += 1
238
+ hintCandidates.push(record)
239
+ omitted.push({ id: record.id, reason: 'budget', kind: record.kind, tags: tagsOf(record) })
240
+ continue
241
+ }
55
242
  const line = `- ${record.id.slice(0, 8)} [${digestScopeLabel(record.scope)}/${record.kind}] ${record.content.replace(/\s+/g, ' ').slice(0, 160)}`
56
243
  const cost = estimateTokens(line) + 1
57
- if (tokens + cost > cfg.tokenBudget) break
58
- lines.push(line)
244
+ if (tokens + cost > cfg.tokenBudget) {
245
+ budgetExhausted = true
246
+ omittedBudget += 1
247
+ hintCandidates.push(record)
248
+ omitted.push({ id: record.id, reason: 'budget', kind: record.kind, tags: tagsOf(record) })
249
+ continue
250
+ }
251
+ selected.push(record)
59
252
  tokens += cost
60
253
  }
61
- if (lines.length === 0) return null
62
- return { text: `${HEADER}\n${lines.join('\n')}`, tokens, count: lines.length }
254
+
255
+ const hint = renderHintIndex(hintCandidates, cfg)
256
+ const bodyText = selected.length > 0
257
+ ? `${HEADER}\n${selected.map((record) => `- ${record.id.slice(0, 8)} [${digestScopeLabel(record.scope)}/${record.kind}] ${record.content.replace(/\s+/g, ' ').slice(0, 160)}`).join('\n')}`
258
+ : ''
259
+ const text = [bodyText, hint.text].filter((part) => part !== null && part !== '').join('\n\n')
260
+ if (text === '') return null
261
+
262
+ const stats = {
263
+ candidates: records.length,
264
+ active: active.length,
265
+ injected: selected.length,
266
+ omittedTopK,
267
+ omittedBudget,
268
+ omittedSuperseded,
269
+ omittedExpired,
270
+ truncated: omitted.length > 0,
271
+ omitted,
272
+ hint: {
273
+ candidates: hintCandidates.length,
274
+ injected: hint.injected,
275
+ omittedTopK: hint.omittedTopK,
276
+ omittedBudget: hint.omittedBudget,
277
+ tokens: hint.tokens,
278
+ budget: cfg.hintBudget,
279
+ maxItems: cfg.hintMaxItems,
280
+ },
281
+ bodyIds: selected.map((record) => record.id),
282
+ hintIds: hint.injectedIds,
283
+ bodyEntries: selected.map((record) => ({ id: record.id, updatedAt: record.updatedAt })),
284
+ hintEntries: hintCandidates
285
+ .filter((record) => hint.injectedIds.includes(record.id))
286
+ .map((record) => ({ id: record.id, updatedAt: record.updatedAt })),
287
+ }
288
+
289
+ return { text, tokens, count: selected.length, stats }
63
290
  }
64
291
 
292
+ /** 兼容旧调用:只要文本。新代码应使用 renderDigest 以取得截断统计与 hintIds。 */
293
+ export function renderDigestBlock(
294
+ records ,
295
+ cfg ,
296
+ now = Date.now(),
297
+ ) {
298
+ return renderDigest(records, cfg, now)
299
+ }
300
+
301
+
65
302
  //# sourceURL=source/memory-inject/src/digest.ts