@restregular/dsh-memory 0.17.1 → 0.19.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.
@@ -37,18 +37,54 @@ import { canonicalWorkspacePath, normalizeScopeInput, resolveScopeRef } from '..
37
37
 
38
38
 
39
39
 
40
+ /** 范围外访问的处理方式(与 provider 的会话可见域一致)。 */
41
+
42
+
43
+
44
+
45
+                 
46
+
47
+
48
+
49
+ /** provider 解析出的生效可见域;undefined = 没有覆盖(不限制)。 */
50
+
51
+
52
+
53
+
54
+
55
+ /** 一条范围外命中,交给审批浮层展示。 */
56
+
57
+
58
+
59
+
60
+
61
+
62
+
63
+
64
+
65
+
66
+
40
67
  /** 只有这一层需要的能力子集(provider 在宿主里提供,测试里可以 mock)。 */
41
68
 
42
69
 
43
-
70
+
44
71
 
45
-
72
+
46
73
                  
47
74
 
48
75
                          
49
76
 
50
77
                      
51
78
 
79
+
80
+                               
81
+          
82
+
83
+
84
+                         
85
+
86
+                             
87
+
52
88
                            
53
89
 
54
90
                 
@@ -113,8 +149,120 @@ function projectKey(opts , service , agent
113
149
  return (opts.projectScope ?? `project:${process.cwd()}`)
114
150
  }
115
151
 
152
+ /**
153
+ * 显式「可见范围」白名单;undefined = 没有覆盖(保持旧行为,不限制显式 scope)。
154
+ * provider 方法抛错时按"没有覆盖"处理:可见范围是防越界,不应该让一个 provider
155
+ * 内部错误把所有读取都锁死。
156
+ */
157
+ function visibleScopeList(service , agent ) {
158
+ try {
159
+ const explicit = service.visibleScopes?.(agent)
160
+ if (Array.isArray(explicit)) return [...new Set(explicit)]
161
+ } catch { /* 降级为不限制 */ }
162
+ return undefined
163
+ }
164
+
165
+ /** 完整可见域;老 provider / 解析失败时退化为 undefined(不限制)。 */
166
+ function visibilityPolicy(service , agent ) {
167
+ try {
168
+ const policy = service.visibilityPolicy?.(agent)
169
+ if (policy !== undefined && policy !== null) {
170
+ const level = policy.level === 'absolute' || policy.level === 'none' ? policy.level : 'normal'
171
+ return { level, scopes: Array.isArray(policy.scopes) ? policy.scopes : [] }
172
+ }
173
+ } catch { /* 降级为不限制 */ }
174
+ return undefined
175
+ }
176
+
177
+ function scopeInPolicy(policy , scope ) {
178
+ if (policy === undefined || policy.level === 'none') return true
179
+ return policy.scopes.some((rule) => rule.scope === scope)
180
+ }
181
+
182
+ /** 这条记录是否在可见域内(scope 与类型都要满足)。 */
183
+ function recordAllowed(policy , scope , kind ) {
184
+ if (policy === undefined || policy.level === 'none') return true
185
+ const rule = policy.scopes.find((item) => item.scope === scope)
186
+ if (rule === undefined) return false
187
+ return rule.kinds === undefined || rule.kinds.length === 0 || rule.kinds.includes(kind)
188
+ }
189
+
190
+ /** 记录在可见域外时,是"整个 scope 不可见"还是"只是类型不允许"。 */
191
+ function outsideReason(policy , scope ) {
192
+ return scopeInPolicy(policy, scope) ? 'kind' : 'scope'
193
+ }
194
+
195
+ function recordsToApprovalItems(
196
+ policy ,
197
+ records ,
198
+ ) {
199
+ return records.map((record) => ({
200
+ id: record.id,
201
+ scope: record.scope,
202
+ kind: record.kind,
203
+ content: record.content,
204
+ tags: Array.isArray(record.tags) ? record.tags : [],
205
+ importance: typeof record.importance === 'number' ? record.importance : 0,
206
+ updatedAt: record.updatedAt,
207
+ reason: outsideReason(policy, record.scope),
208
+ }))
209
+ }
210
+
211
+ /**
212
+ * 普通限制:把范围外命中交给用户审批一次。
213
+ * provider 不支持审批(旧版本)时按拒绝处理 —— 不能静默把范围外记忆放出去。
214
+ */
215
+ async function askOutOfScope(
216
+ service ,
217
+ agent ,
218
+ policy ,
219
+ tool ,
220
+ query ,
221
+ records ,
222
+ signal ,
223
+ ) {
224
+ if (records.length === 0) return true
225
+ if (typeof service.requestOutOfScope !== 'function') return false
226
+ if (signal?.aborted) return false
227
+ try {
228
+ const outcome = await service.requestOutOfScope(agent, {
229
+ tool,
230
+ query,
231
+ items: recordsToApprovalItems(policy, records),
232
+ ...(signal !== undefined ? { signal } : {}),
233
+ })
234
+ return outcome === 'allowed-once'
235
+ } catch {
236
+ return false
237
+ }
238
+ }
239
+
240
+ /** 显式询问一个不在可见范围内的 scope 时给出明确错误,而不是返回空结果。 */
241
+ function assertScopeVisible(service , agent , scope ) {
242
+ const policy = visibilityPolicy(service, agent)
243
+ if (policy === undefined || policy.level === 'none' || scopeInPolicy(policy, scope)) return
244
+ const visible = policy.scopes.map((rule) => rule.scope)
245
+ throw new MemoryToolError(
246
+ 'SCOPE_NOT_VISIBLE',
247
+ `当前会话的「记忆可见域」不包含 ${scope};只能读取: ${visible.length > 0 ? visible.join(', ') : '(无)'}`,
248
+ )
249
+ }
250
+
251
+ /** 规范里所有已知 scope(用来在普通限制下把范围外也搜一遍,看看有没有可审批的命中)。 */
252
+ function allKnownScopes(service ) {
253
+ try {
254
+ service.discoverScopes?.()
255
+ return [...new Set((service.scopeStats?.() ?? []).map((item) => item.scope))]
256
+ } catch {
257
+ return []
258
+ }
259
+ }
260
+
116
261
  /** 该服务/配置下"当前会话 + 当前项目 + global"的合并读取集合(去重)。 */
117
262
  function readScopes(opts , service , agent ) {
263
+ // 显式可见范围优先,空数组也要原样返回(表示什么都不允许读)。
264
+ const explicit = visibleScopeList(service, agent)
265
+ if (explicit !== undefined) return explicit
118
266
  const provided = service.resolveReadScopes?.(agent)
119
267
  if (Array.isArray(provided) && provided.length > 0) return [...new Set(provided)]
120
268
  // 服务没提供(测试 mock / 旧 provider):退回 defaultScope 口径
@@ -309,6 +457,8 @@ export function summarize(content , chars = DEFAULT_SUMMARY_CHARS
309
457
 
310
458
 
311
459
 
460
+                            
461
+
312
462
 
313
463
 
314
464
  export function memorySearchTool(opts ) {
@@ -328,26 +478,56 @@ export function memorySearchTool(opts )
328
478
  throw new MemoryToolError('QUERY_EMPTY', 'query must be a non-empty string')
329
479
  }
330
480
  const resolved = resolveScope(opts, service, exec, args.scope, 'read')
481
+ const agent = agentOf(exec)
482
+ const policy = visibilityPolicy(service, agent)
483
+ const level = policy?.level
484
+ const visible = policy !== undefined && level !== 'none'
485
+ ? policy.scopes.map((rule) => rule.scope)
486
+ : visibleScopeList(service, agent)
331
487
  let scopes
332
488
  if (resolved.all) {
333
- // 'all' = 所有已发现作用域;scopeStats() 自身会先做 discovery(带限流)。
334
- scopes = (service.scopeStats?.() ?? []).map((s) => s.scope)
335
- service.discoverScopes?.()
489
+ if (visible !== undefined) {
490
+ // 'all' 在有可见范围限制时只等于"所有可见范围",不是磁盘上的全部 scope。
491
+ // 普通限制额外把磁盘上其它 scope 也搜一遍,才有"范围外命中"可审批。
492
+ scopes = level === 'normal' ? [...new Set([...visible, ...allKnownScopes(service)])] : visible
493
+ } else {
494
+ scopes = allKnownScopes(service)
495
+ }
336
496
  } else if (resolved.scope === undefined) {
337
- // 省略 scope:三路合并(会话 + 项目 + global)
338
- scopes = readScopes(opts, service, agentOf(exec))
497
+ // 省略 scope:三路合并(会话 + 项目 + global),或显式可见范围。
498
+ const merged = readScopes(opts, service, agent)
499
+ scopes = level === 'normal' ? [...new Set([...merged, ...allKnownScopes(service)])] : merged
500
+ } else if (level === 'absolute') {
501
+ assertScopeVisible(service, agent, resolved.scope)
339
502
  }
340
503
  const chars = resolveSummaryChars(args.summaryChars)
341
504
  try {
505
+ const wantedTopK = args.topK !== undefined ? Math.min(20, Math.max(1, args.topK)) : undefined
342
506
  const hits = await service.search({
343
507
  text: args.query,
344
508
  ...(resolved.scope !== undefined ? { scope: resolved.scope } : {}),
345
509
  ...(scopes !== undefined ? { scopes } : {}),
346
- ...(args.topK !== undefined ? { topK: args.topK } : {}),
510
+ // 多取一些候选,避免范围外命中挤掉范围内的结果。
511
+ topK: Math.min(60, Math.max(10, (wantedTopK ?? 10) * 3)),
347
512
  ...(args.includeSuperseded === true ? { includeSuperseded: true } : {}),
348
513
  })
349
- return {
350
- records: hits.map((h) => ({
514
+ const inside = hits.filter((hit) => recordAllowed(policy, hit.record.scope, hit.record.kind))
515
+ const outside = hits.filter((hit) => !recordAllowed(policy, hit.record.scope, hit.record.kind))
516
+ let granted = false
517
+ if (outside.length > 0 && level === 'normal') {
518
+ granted = await askOutOfScope(
519
+ service,
520
+ agent,
521
+ policy,
522
+ 'memory_search',
523
+ args.query,
524
+ outside.map((hit) => hit.record),
525
+ (exec )?.signal,
526
+ )
527
+ }
528
+ const selected = granted ? hits : inside
529
+ const result = {
530
+ records: selected.map((h) => ({
351
531
  id: h.record.id,
352
532
  score: h.score,
353
533
  scope: h.record.scope,
@@ -357,6 +537,11 @@ export function memorySearchTool(opts )
357
537
  summary: summarize(h.record.content, chars),
358
538
  })),
359
539
  }
540
+ if (!granted && outside.length > 0) {
541
+ result.withheld = { count: outside.length, reason: level === 'normal' ? 'rejected' : 'absolute' }
542
+ }
543
+ if (wantedTopK !== undefined) result.records = result.records.slice(0, wantedTopK)
544
+ return result
360
545
  } catch (error) {
361
546
  throw toolError(error)
362
547
  }
@@ -420,6 +605,8 @@ export function memoryForgetTool(opts )
420
605
 
421
606
                                 
422
607
 
608
+                            
609
+
423
610
 
424
611
 
425
612
  export function memoryListTool(opts ) {
@@ -434,34 +621,74 @@ export function memoryListTool(opts )
434
621
  async execute(args , exec ) {
435
622
  const service = svc(opts)
436
623
  const resolved = resolveScope(opts, service, exec, args.scope, 'read')
624
+ const agent = agentOf(exec)
625
+ const policy = visibilityPolicy(service, agent)
626
+ const level = policy?.level
627
+ const visible = policy !== undefined && level !== 'none'
628
+ ? policy.scopes.map((rule) => rule.scope)
629
+ : visibleScopeList(service, agent)
437
630
  let scopes
438
631
  if (resolved.all) {
439
- scopes = (service.scopeStats?.() ?? []).map((s) => s.scope)
440
- service.discoverScopes?.()
632
+ if (visible !== undefined) {
633
+ scopes = level === 'normal' ? [...new Set([...visible, ...allKnownScopes(service)])] : visible
634
+ } else {
635
+ scopes = allKnownScopes(service)
636
+ }
441
637
  } else if (resolved.scope === undefined) {
442
- // 省略 scope:默认**只列当前会话**(按需求;读全部请显式 'all')
443
- scopes = readScopes(opts, service, agentOf(exec)).slice(0, 1)
638
+ // 省略 scope:默认**只列当前会话**(按需求;读全部请显式 'all')。
639
+ // 这是有意为之的窄口径,不因为"普通限制"就去列范围外的东西。
640
+ scopes = readScopes(opts, service, agent).slice(0, 1)
641
+ } else if (level === 'absolute') {
642
+ assertScopeVisible(service, agent, resolved.scope)
444
643
  }
445
644
  let records
645
+ let withheld
446
646
  try {
647
+ const limit = args.limit !== undefined ? Math.min(200, Math.max(1, args.limit)) : 50
447
648
  const raw = await service.list({
448
649
  ...(resolved.scope !== undefined ? { scope: resolved.scope } : {}),
449
650
  ...(scopes !== undefined ? { scopes } : {}),
450
651
  ...(args.kind ? { kind: args.kind } : {}),
451
- ...(args.limit !== undefined ? { limit: args.limit } : {}),
652
+ // 多取一些候选,避免范围外记录挤掉范围内结果。
653
+ limit: Math.min(200, Math.max(limit, limit * 2)),
452
654
  })
453
- records = raw.map((r) => ({
655
+ const inside = raw.filter((record) => recordAllowed(policy, record.scope, record.kind))
656
+ const outside = raw.filter((record) => !recordAllowed(policy, record.scope, record.kind))
657
+ let granted = false
658
+ if (outside.length > 0 && level === 'normal') {
659
+ granted = await askOutOfScope(
660
+ service,
661
+ agent,
662
+ policy,
663
+ 'memory_list',
664
+ resolved.scope ?? args.scope ?? 'all',
665
+ outside,
666
+ (exec )?.signal,
667
+ )
668
+ }
669
+ const selected = (granted ? raw : inside).slice(0, limit)
670
+ records = selected.map((r) => ({
454
671
  id: r.id,
455
672
  scope: r.scope,
456
673
  kind: r.kind,
457
674
  updatedAt: r.updatedAt,
458
675
  content: r.content,
459
676
  }))
677
+ if (!granted && outside.length > 0) {
678
+ withheld = { count: outside.length, reason: level === 'normal' ? 'rejected' : 'absolute' }
679
+ }
460
680
  } catch (error) {
461
681
  throw toolError(error)
462
682
  }
463
- const stats = service.scopeStats?.()
464
- return stats !== undefined ? { records, scopeStats: stats } : { records }
683
+ const statsAll = service.scopeStats?.()
684
+ const stats = statsAll !== undefined && visible !== undefined
685
+ ? statsAll.filter((s) => visible.includes(s.scope))
686
+ : statsAll
687
+ return {
688
+ records,
689
+ ...(stats !== undefined ? { scopeStats: stats } : {}),
690
+ ...(withheld !== undefined ? { withheld } : {}),
691
+ }
465
692
  },
466
693
  }
467
694
  }
@@ -501,6 +728,8 @@ export const DEFAULT_GET_FIELDS = ['content', 'scope', 'kind', 'tags
501
728
                            
502
729
 
503
730
 
731
+                              
732
+
504
733
 
505
734
 
506
735
  const FIELD_BY_LOWER = new Map (GET_FIELDS.map((field) => [field.toLowerCase(), field]))
@@ -570,7 +799,7 @@ export function memoryGetTool(opts )
570
799
  },
571
800
  summaryChars: { type: 'number', description: `summary 字段的字数上限(默认 ${DEFAULT_SUMMARY_CHARS},20~2000)` },
572
801
  },
573
- async execute(args ) {
802
+ async execute(args , exec ) {
574
803
  const service = svc(opts)
575
804
  const ids = Array.isArray(args.ids)
576
805
  ? [...new Set(args.ids.map(String).filter((id) => id.trim() !== ''))].slice(0, 50)
@@ -582,11 +811,33 @@ export function memoryGetTool(opts )
582
811
  const fields = resolveGetFields(args.fields)
583
812
  const chars = resolveSummaryChars(args.summaryChars)
584
813
  try {
585
- const found = service.getByIds(ids)
814
+ const all = service.getByIds(ids)
815
+ // 可见域是白名单:即使知道 id,也不能直接读别的范围/别的类型的正文。
816
+ const agent = agentOf(exec)
817
+ const policy = visibilityPolicy(service, agent)
818
+ const level = policy?.level
819
+ const inside = all.filter((record) => recordAllowed(policy, record.scope, record.kind))
820
+ const outside = all.filter((record) => !recordAllowed(policy, record.scope, record.kind))
821
+ let granted = false
822
+ if (outside.length > 0 && level === 'normal') {
823
+ granted = await askOutOfScope(
824
+ service,
825
+ agent,
826
+ policy,
827
+ 'memory_get',
828
+ ids.join(' '),
829
+ outside,
830
+ (exec )?.signal,
831
+ )
832
+ }
833
+ const found = granted ? all : inside
586
834
  return {
587
835
  records: found.map((r) => pickGetFields(r, fields, chars)),
588
836
  fields,
589
837
  missing: ids.filter((token) => !found.some((r) => r.id === token || r.id.startsWith(token))),
838
+ ...(!granted && outside.length > 0
839
+ ? { withheld: { count: outside.length, reason: level === 'normal' ? 'rejected' : 'absolute' } }
840
+ : {}),
590
841
  }
591
842
  } catch (error) {
592
843
  throw toolError(error)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@restregular/dsh-memory",
3
- "version": "0.17.1",
3
+ "version": "0.19.0",
4
4
  "description": "DeepSeek Harness 记忆系统(单包单入口):JSONL 存储 + 本地向量检索(BGE-M3)+ 五个模型工具 + 自动召回注入 + 管理面板。",
5
5
  "icon": "./icon.svg",
6
6
  "type": "module",