@restregular/dsh-memory 0.18.0 → 0.19.1

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,12 +37,39 @@ 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
                          
@@ -54,6 +81,10 @@ import { canonicalWorkspacePath, normalizeScopeInput, resolveScopeRef } from '..
54
81
           
55
82
 
56
83
 
84
+                         
85
+
86
+                             
87
+
57
88
                            
58
89
 
59
90
                 
@@ -131,16 +162,102 @@ function visibleScopeList(service , agent )
131
162
  return undefined
132
163
  }
133
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
+
134
240
  /** 显式询问一个不在可见范围内的 scope 时给出明确错误,而不是返回空结果。 */
135
241
  function assertScopeVisible(service , agent , scope ) {
136
- const visible = visibleScopeList(service, agent)
137
- if (visible === undefined || visible.includes(scope)) return
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)
138
245
  throw new MemoryToolError(
139
246
  'SCOPE_NOT_VISIBLE',
140
- `当前会话的「记忆可见范围」不包含 ${scope};只能读取: ${visible.length > 0 ? visible.join(', ') : '(无)'}`,
247
+ `当前会话的「记忆可见域」不包含 ${scope};只能读取: ${visible.length > 0 ? visible.join(', ') : '(无)'}`,
141
248
  )
142
249
  }
143
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
+
144
261
  /** 该服务/配置下"当前会话 + 当前项目 + global"的合并读取集合(去重)。 */
145
262
  function readScopes(opts , service , agent ) {
146
263
  // 显式可见范围优先,空数组也要原样返回(表示什么都不允许读)。
@@ -340,6 +457,8 @@ export function summarize(content , chars = DEFAULT_SUMMARY_CHARS
340
457
 
341
458
 
342
459
 
460
+                            
461
+
343
462
 
344
463
 
345
464
  export function memorySearchTool(opts ) {
@@ -360,34 +479,55 @@ export function memorySearchTool(opts )
360
479
  }
361
480
  const resolved = resolveScope(opts, service, exec, args.scope, 'read')
362
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)
363
487
  let scopes
364
488
  if (resolved.all) {
365
- const visible = visibleScopeList(service, agent)
366
489
  if (visible !== undefined) {
367
490
  // 'all' 在有可见范围限制时只等于"所有可见范围",不是磁盘上的全部 scope。
368
- scopes = visible
491
+ // 普通限制额外把磁盘上其它 scope 也搜一遍,才有"范围外命中"可审批。
492
+ scopes = level === 'normal' ? [...new Set([...visible, ...allKnownScopes(service)])] : visible
369
493
  } else {
370
- // 'all' = 所有已发现作用域;scopeStats() 自身会先做 discovery(带限流)。
371
- scopes = (service.scopeStats?.() ?? []).map((s) => s.scope)
372
- service.discoverScopes?.()
494
+ scopes = allKnownScopes(service)
373
495
  }
374
496
  } else if (resolved.scope === undefined) {
375
497
  // 省略 scope:三路合并(会话 + 项目 + global),或显式可见范围。
376
- scopes = readScopes(opts, service, agent)
377
- } else {
498
+ const merged = readScopes(opts, service, agent)
499
+ scopes = level === 'normal' ? [...new Set([...merged, ...allKnownScopes(service)])] : merged
500
+ } else if (level === 'absolute') {
378
501
  assertScopeVisible(service, agent, resolved.scope)
379
502
  }
380
503
  const chars = resolveSummaryChars(args.summaryChars)
381
504
  try {
505
+ const wantedTopK = args.topK !== undefined ? Math.min(20, Math.max(1, args.topK)) : undefined
382
506
  const hits = await service.search({
383
507
  text: args.query,
384
508
  ...(resolved.scope !== undefined ? { scope: resolved.scope } : {}),
385
509
  ...(scopes !== undefined ? { scopes } : {}),
386
- ...(args.topK !== undefined ? { topK: args.topK } : {}),
510
+ // 多取一些候选,避免范围外命中挤掉范围内的结果。
511
+ topK: Math.min(60, Math.max(10, (wantedTopK ?? 10) * 3)),
387
512
  ...(args.includeSuperseded === true ? { includeSuperseded: true } : {}),
388
513
  })
389
- return {
390
- 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) => ({
391
531
  id: h.record.id,
392
532
  score: h.score,
393
533
  scope: h.record.scope,
@@ -397,6 +537,11 @@ export function memorySearchTool(opts )
397
537
  summary: summarize(h.record.content, chars),
398
538
  })),
399
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
400
545
  } catch (error) {
401
546
  throw toolError(error)
402
547
  }
@@ -460,6 +605,8 @@ export function memoryForgetTool(opts )
460
605
 
461
606
                                 
462
607
 
608
+                            
609
+
463
610
 
464
611
 
465
612
  export function memoryListTool(opts ) {
@@ -475,44 +622,73 @@ export function memoryListTool(opts )
475
622
  const service = svc(opts)
476
623
  const resolved = resolveScope(opts, service, exec, args.scope, 'read')
477
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)
478
630
  let scopes
479
631
  if (resolved.all) {
480
- const visible = visibleScopeList(service, agent)
481
- if (visible !== undefined) scopes = visible
482
- else {
483
- scopes = (service.scopeStats?.() ?? []).map((s) => s.scope)
484
- service.discoverScopes?.()
632
+ if (visible !== undefined) {
633
+ scopes = level === 'normal' ? [...new Set([...visible, ...allKnownScopes(service)])] : visible
634
+ } else {
635
+ scopes = allKnownScopes(service)
485
636
  }
486
637
  } else if (resolved.scope === undefined) {
487
- // 省略 scope:默认**只列当前会话**(按需求;读全部请显式 'all')
638
+ // 省略 scope:默认**只列当前会话**(按需求;读全部请显式 'all')。
639
+ // 这是有意为之的窄口径,不因为"普通限制"就去列范围外的东西。
488
640
  scopes = readScopes(opts, service, agent).slice(0, 1)
489
- } else {
641
+ } else if (level === 'absolute') {
490
642
  assertScopeVisible(service, agent, resolved.scope)
491
643
  }
492
644
  let records
645
+ let withheld
493
646
  try {
647
+ const limit = args.limit !== undefined ? Math.min(200, Math.max(1, args.limit)) : 50
494
648
  const raw = await service.list({
495
649
  ...(resolved.scope !== undefined ? { scope: resolved.scope } : {}),
496
650
  ...(scopes !== undefined ? { scopes } : {}),
497
651
  ...(args.kind ? { kind: args.kind } : {}),
498
- ...(args.limit !== undefined ? { limit: args.limit } : {}),
652
+ // 多取一些候选,避免范围外记录挤掉范围内结果。
653
+ limit: Math.min(200, Math.max(limit, limit * 2)),
499
654
  })
500
- 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) => ({
501
671
  id: r.id,
502
672
  scope: r.scope,
503
673
  kind: r.kind,
504
674
  updatedAt: r.updatedAt,
505
675
  content: r.content,
506
676
  }))
677
+ if (!granted && outside.length > 0) {
678
+ withheld = { count: outside.length, reason: level === 'normal' ? 'rejected' : 'absolute' }
679
+ }
507
680
  } catch (error) {
508
681
  throw toolError(error)
509
682
  }
510
683
  const statsAll = service.scopeStats?.()
511
- const visible = visibleScopeList(service, agent)
512
684
  const stats = statsAll !== undefined && visible !== undefined
513
685
  ? statsAll.filter((s) => visible.includes(s.scope))
514
686
  : statsAll
515
- return stats !== undefined ? { records, scopeStats: stats } : { records }
687
+ return {
688
+ records,
689
+ ...(stats !== undefined ? { scopeStats: stats } : {}),
690
+ ...(withheld !== undefined ? { withheld } : {}),
691
+ }
516
692
  },
517
693
  }
518
694
  }
@@ -552,6 +728,8 @@ export const DEFAULT_GET_FIELDS = ['content', 'scope', 'kind', 'tags
552
728
                            
553
729
 
554
730
 
731
+                              
732
+
555
733
 
556
734
 
557
735
  const FIELD_BY_LOWER = new Map (GET_FIELDS.map((field) => [field.toLowerCase(), field]))
@@ -634,14 +812,32 @@ export function memoryGetTool(opts )
634
812
  const chars = resolveSummaryChars(args.summaryChars)
635
813
  try {
636
814
  const all = service.getByIds(ids)
637
- // 显式可见范围是白名单:即使知道 id,也不能读别的范围的正文。未设置时保持
638
- // 旧行为(记忆 id 本身是随机不可猜的,跨 scope 取全文是既有能力)。
639
- const visible = visibleScopeList(service, agentOf(exec))
640
- const found = visible === undefined ? all : all.filter((r) => visible.includes(r.scope))
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
641
834
  return {
642
835
  records: found.map((r) => pickGetFields(r, fields, chars)),
643
836
  fields,
644
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
+ : {}),
645
841
  }
646
842
  } catch (error) {
647
843
  throw toolError(error)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@restregular/dsh-memory",
3
- "version": "0.18.0",
3
+ "version": "0.19.1",
4
4
  "description": "DeepSeek Harness 记忆系统(单包单入口):JSONL 存储 + 本地向量检索(BGE-M3)+ 五个模型工具 + 自动召回注入 + 管理面板。",
5
5
  "icon": "./icon.svg",
6
6
  "type": "module",