@restregular/dsh-memory 0.23.0 → 0.24.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.
@@ -35,6 +35,8 @@ import { canonicalWorkspacePath, normalizeScopeInput, resolveScopeRef } from '..
35
35
 
36
36
 
37
37
 
38
+                       
39
+
38
40
 
39
41
 
40
42
  /** 范围外访问的处理方式(与 provider 的会话可见域一致)。 */
@@ -64,7 +66,7 @@ import { canonicalWorkspacePath, normalizeScopeInput, resolveScopeRef } from '..
64
66
  * - absolute = 绝对限制下作用域根本不在范围内(0.23 起不再假装"不存在");
65
67
  * - read-disabled = 作用域在范围内但「可读」开关被关掉(0.23)。
66
68
  */
67
-
69
+
68
70
 
69
71
 
70
72
 
@@ -115,6 +117,64 @@ import { canonicalWorkspacePath, normalizeScopeInput, resolveScopeRef } from '..
115
117
 
116
118
        
117
119
 
120
+
121
+
122
+ /**
123
+ * 目录工具的一行(与 provider 的 ScopeCatalogEntry 同形)。
124
+ * `absolute` 下范围外条目仍会出现,但 readable/writable/canRequest* 全为 false。
125
+ */
126
+
127
+
128
+
129
+
130
+
131
+
132
+
133
+
134
+
135
+
136
+
137
+
138
+
139
+                
140
+
141
+
142
+
143
+ /** provider 统一授权判定的结果(0.24.0)。 */
144
+
145
+
146
+
147
+                     
148
+
149
+
150
+
151
+
152
+
153
+
154
+
155
+
156
+
157
+ /** 一条作用域权限申请的结果(0.24.0 / D3)。 */
158
+
159
+
160
+
161
+
162
+
163
+
164
+
165
+
166
+
167
+
168
+
169
+
170
+
171
+
172
+
173
+
174
+
175
+
176
+
177
+
118
178
 
119
179
 
120
180
  /** 只有这一层需要的能力子集(provider 在宿主里提供,测试里可以 mock)。 */
@@ -127,6 +187,23 @@ import { canonicalWorkspacePath, normalizeScopeInput, resolveScopeRef } from '..
127
187
 
128
188
                          
129
189
 
190
+                               
191
+
192
+
193
+                   
194
+                               
195
+
196
+
197
+
198
+                    
199
+                     
200
+
201
+
202
+
203
+
204
+
205
+
206
+
130
207
                      
131
208
 
132
209
 
@@ -180,7 +257,8 @@ import { canonicalWorkspacePath, normalizeScopeInput, resolveScopeRef } from '..
180
257
 
181
258
  const SCOPE_DESCRIPTION =
182
259
  "省略=当前会话;'global'=所有项目共享;'project'=当前工作区;其他任意名称=自定义作用域"
183
- + "(memory_save 时不存在则自动创建)。读取时可用 'all' 跨所有作用域。"
260
+ + "(memory_save 时不存在则自动创建;由 Agent 创建时必须同时提供 scopeDescription 说明用途)。"
261
+ + "读取时可用 'all' 跨所有作用域。"
184
262
 
185
263
  export class MemoryToolError extends Error {
186
264
  code
@@ -275,8 +353,8 @@ function policyRule(policy , scope )
275
353
  return policy.scopes.find((item) => item.scope === scope)
276
354
  }
277
355
 
278
- /** 这条记录是否在可见域内(scope、read 开关与类型都要满足)。 */
279
- function recordAllowed(policy , scope , kind ) {
356
+ /** 这条记录是否在可见域内(旧 provider 的纯策略回退;新 provider 走 authorize)。 */
357
+ function legacyRecordAllowed(policy , scope , kind ) {
280
358
  if (policy === undefined || policy.level === 'none') return true
281
359
  const rule = policyRule(policy, scope)
282
360
  if (rule === undefined || rule.read === false) return false
@@ -288,14 +366,96 @@ function outsideReason(policy , scope )
288
366
  return scopeInPolicy(policy, scope) ? 'kind' : 'scope'
289
367
  }
290
368
 
291
- /** 范围被挡住时给模型的原因:绝对限制 / 可读开关 / 普通审批结局。 */
369
+ /** provider 的授权判定器;老 provider / 拿不到会话时返回 undefined(走回退)。 */
370
+
371
+
372
+
373
+
374
+
375
+
376
+ function decisionMaker(service , agent ) {
377
+ if (agent === undefined) return () => undefined
378
+ try {
379
+ const evaluator = service.accessEvaluator?.(agent)
380
+ if (typeof evaluator === 'function') {
381
+ return (action, scope, kind) => {
382
+ try {
383
+ return evaluator({ scope, action, ...(kind !== undefined ? { kind } : {}) })
384
+ } catch {
385
+ return undefined
386
+ }
387
+ }
388
+ }
389
+ } catch { /* 回退到纯策略判定 */ }
390
+ return () => undefined
391
+ }
392
+
393
+ /** 读权限:优先 provider 的统一判定,老 provider 用纯策略回退。 */
394
+ function recordAllowed(
395
+ decide ,
396
+ policy ,
397
+ scope ,
398
+ kind ,
399
+ ) {
400
+ const decision = decide('read', scope, kind)
401
+ return decision !== undefined ? decision.allowed : legacyRecordAllowed(policy, scope, kind)
402
+ }
403
+
404
+ /** 这条被挡住的读能不能申请审批;absolute 与显式 read:false 都不能。 */
405
+ function recordRequestable(
406
+ decide ,
407
+ policy ,
408
+ scope ,
409
+ kind ,
410
+ ) {
411
+ const decision = decide('read', scope, kind)
412
+ if (decision !== undefined) return !decision.allowed && decision.requestable
413
+ return policy?.level === 'normal' && policyRule(policy, scope) === undefined
414
+ }
415
+
416
+ /** 写权限:优先 provider 的统一判定,老 provider 用纯策略回退。 */
417
+ function scopeWritableBy(
418
+ decide ,
419
+ service ,
420
+ agent ,
421
+ policy ,
422
+ scope ,
423
+ ) {
424
+ const decision = decide('write', scope)
425
+ if (decision !== undefined) return decision.allowed
426
+ return scopeWritable(service, agent, policy, scope)
427
+ }
428
+
429
+ /** 单条读被挡住的原因(给 withheld 用)。 */
430
+ function readDenyReason(
431
+ decide ,
432
+ policy ,
433
+ scope ,
434
+ kind ,
435
+ ) {
436
+ const decision = decide('read', scope, kind)
437
+ switch (decision?.reason) {
438
+ case 'ABSOLUTE_ISOLATION': return 'absolute'
439
+ case 'SCOPE_DISABLED': return 'scope-disabled'
440
+ case 'READ_DISABLED': return 'read-disabled'
441
+ case 'KIND_NOT_ALLOWED': return 'read-disabled'
442
+ case 'SCOPE_NOT_IN_RANGE': return policy?.level === 'absolute' ? 'absolute' : 'read-disabled'
443
+ }
444
+ return policy?.level === 'absolute' ? 'absolute' : 'read-disabled'
445
+ }
446
+
447
+ /** 范围被挡住时给模型的原因:审批结局优先,否则按实际拒绝原因聚合。 */
292
448
  function withheldReasonFor(
449
+ decide ,
293
450
  policy ,
451
+ denied ,
294
452
  verdict ,
295
- hasAbsolute ,
296
453
  ) {
297
454
  if (verdict !== undefined) return verdict.outcome === 'allowed-once' ? 'partial' : verdict.outcome
298
- if (policy !== undefined && policy.level === 'absolute' && hasAbsolute) return 'absolute'
455
+ if (denied.length === 0) return undefined
456
+ const reasons = denied.map((item) => readDenyReason(decide, policy, item.scope, item.kind))
457
+ if (reasons.includes('absolute')) return 'absolute'
458
+ if (reasons.includes('scope-disabled')) return 'scope-disabled'
299
459
  return 'read-disabled'
300
460
  }
301
461
 
@@ -459,6 +619,41 @@ function blockedRecordError(policy , scope
459
619
  )
460
620
  }
461
621
 
622
+ /** 按 id 删除时,记录存在但被 provider 的授权判定挡住的原因。 */
623
+ function blockedRecordDecisionError(decision , scope , id ) {
624
+ if (decision.reason === 'WRITE_DISABLED') {
625
+ return new MemoryToolError(
626
+ 'SCOPE_READ_ONLY',
627
+ `记忆 ${id} 所在作用域 ${scope} 在本会话记忆范围里被标记为「不可写」,本次删除没有执行。如需删除,请让用户打开该作用域的「可写」状态。`,
628
+ )
629
+ }
630
+ if (decision.reason === 'SCOPE_DISABLED') {
631
+ return new MemoryToolError('SCOPE_DISABLED', `记忆 ${id} 所在作用域 ${scope} 已被配置关闭,本次删除没有执行。`)
632
+ }
633
+ return new MemoryToolError(
634
+ 'VISIBILITY_ABSOLUTE',
635
+ `记忆 ${id} 不在本会话可见范围内(限制等级:绝对限制),本次删除没有执行。如需删除,请让用户调整「记忆范围」后重试。`,
636
+ )
637
+ }
638
+
639
+ /** 写入/删除被 provider 的授权判定挡住时给模型的真实原因。 */
640
+ function writeDecisionError(decision , scope , action ) {
641
+ const verb = action === 'write' ? '写入' : '删除'
642
+ if (decision.reason === 'WRITE_DISABLED') {
643
+ return new MemoryToolError(
644
+ 'SCOPE_READ_ONLY',
645
+ `作用域 ${scope} 在本会话记忆范围里被标记为「不可写」(可读/可写按钮),本次${verb}没有执行。如需${verb},请让用户打开该作用域的「可写」状态。`,
646
+ )
647
+ }
648
+ if (decision.reason === 'SCOPE_DISABLED') {
649
+ return new MemoryToolError('SCOPE_DISABLED', `作用域 ${scope} 已被配置关闭,本次${verb}没有执行。`)
650
+ }
651
+ return new MemoryToolError(
652
+ 'VISIBILITY_ABSOLUTE',
653
+ `作用域 ${scope} 不在本会话可见范围内(限制等级:绝对限制),本次${verb}没有执行。如需${verb},请让用户调整「记忆范围」后重试。`,
654
+ )
655
+ }
656
+
462
657
  /** 写入/删除前判断一个 scope 是否可写(0.23 起独立于 read 开关)。 */
463
658
  function scopeWritable(service , agent , policy , scope ) {
464
659
  if (policy === undefined || policy.level === 'none') return true
@@ -542,6 +737,13 @@ function resolveScope(
542
737
 
543
738
                              
544
739
 
740
+
741
+                             
742
+                          
743
+
744
+
745
+                           
746
+
545
747
                              
546
748
 
547
749
 
@@ -582,6 +784,8 @@ export function memorySaveTool(opts )
582
784
  expiresAt: { type: 'number', description: '过期时间(毫秒时间戳)。kind=state 不传时按设置里的默认 TTL(7 天)' },
583
785
  ttlMs: { type: 'number', description: '相对有效期(毫秒)。与 expiresAt 二选一,expiresAt 优先' },
584
786
  triggers: { type: 'array', items: { type: 'string' }, description: '流程触发词(kind=procedure):工具名/关键词/路径;缺省用 tags' },
787
+ scopeDescription: { type: 'string', description: '新建自定义作用域时必填:一句话说明这个作用域用来做什么(已有作用域带上它 = 更新用途)' },
788
+ scopeRule: { type: 'string', description: '初始化时可选写一条初始规则(kind=rule):只对新自定义作用域生效,用于约定该作用域只记录什么、不记录什么' },
585
789
  description: { type: 'string', description: DESCRIPTION_PARAM_DESCRIPTION },
586
790
  },
587
791
  async execute(args , exec ) {
@@ -629,12 +833,17 @@ export function memorySaveTool(opts )
629
833
  // - none → 不限制。
630
834
  // 拿不到会话(老宿主 / 无 exec)时不判断:没有会话就没有"本会话的可见域"。
631
835
  const policy = agent === undefined ? undefined : visibilityPolicy(service, agent)
836
+ const decide = decisionMaker(service, agent)
632
837
  const level = policy?.level ?? 'none'
633
838
  const target = explicit ?? (typeof service.resolveWriteScope === 'function' ? service.resolveWriteScope(agent) : undefined)
634
839
  let approved = false
635
- if (level !== 'none' && target !== undefined && !scopeWritable(service, agent, policy, target)) {
636
- const rule = policyRule(policy, target)
637
- if (rule !== undefined || level === 'absolute') {
840
+ if (level !== 'none' && target !== undefined && !scopeWritableBy(decide, service, agent, policy, target)) {
841
+ const decision = decide('write', target)
842
+ if (decision !== undefined) {
843
+ // provider 已经给出统一判定:不可申请就直接讲原因(absolute / 关闭 / 只读)。
844
+ if (!decision.requestable) throw writeDecisionError(decision, target, 'write')
845
+ } else if (policyRule(policy, target) !== undefined || level === 'absolute') {
846
+ // 老 provider 没有授权判定时保持原有纯策略判断。
638
847
  throw scopeWriteBlockedError(policy, target, 'write')
639
848
  }
640
849
  const draft = {
@@ -677,6 +886,12 @@ export function memorySaveTool(opts )
677
886
  ...(typeof args.expiresAt === 'number' ? { expiresAt: args.expiresAt } : {}),
678
887
  ...(typeof args.ttlMs === 'number' ? { ttlMs: args.ttlMs } : {}),
679
888
  ...(Array.isArray(args.triggers) ? { triggers: args.triggers.map(String) } : {}),
889
+ ...(typeof args.scopeDescription === 'string' && args.scopeDescription.trim() !== ''
890
+ ? { scopeDescription: args.scopeDescription }
891
+ : {}),
892
+ ...(typeof args.scopeRule === 'string' && args.scopeRule.trim() !== ''
893
+ ? { scopeRule: args.scopeRule }
894
+ : {}),
680
895
  source: { origin: 'explicit' },
681
896
  })
682
897
  return { id: record.id, scope: record.scope, ...(alias !== undefined ? { scopeName: alias } : {}), deduped: false }
@@ -785,6 +1000,7 @@ export function memorySearchTool(opts )
785
1000
  }
786
1001
  const resolved = resolveScope(opts, service, exec, args.scope, 'read')
787
1002
  const policy = visibilityPolicy(service, agent)
1003
+ const decide = decisionMaker(service, agent)
788
1004
  const level = policy?.level ?? 'none'
789
1005
  // level=none 时策略里的 scopes 只是偏好,不参与限制(等价于没有可见域)。
790
1006
  const visible = policy !== undefined && policy.level !== 'none' ? policy.scopes.map((rule) => rule.scope) : undefined
@@ -818,10 +1034,10 @@ export function memorySearchTool(opts )
818
1034
  topK: Math.min(60, Math.max(10, (wantedTopK ?? 10) * 3)),
819
1035
  ...(args.includeSuperseded === true ? { includeSuperseded: true } : {}),
820
1036
  })
821
- const inside = hits.filter((hit) => recordAllowed(policy, hit.record.scope, hit.record.kind))
822
- const outside = hits.filter((hit) => !recordAllowed(policy, hit.record.scope, hit.record.kind))
823
- // 只有"作用域不在范围里"才可能审批;read:false 的作用域显式不可读,审批也不该放行。
824
- const needsApproval = outside.filter((hit) => policyRule(policy, hit.record.scope) === undefined || policyRule(policy, hit.record.scope)?.read !== false)
1037
+ const inside = hits.filter((hit) => recordAllowed(decide, policy, hit.record.scope, hit.record.kind))
1038
+ const outside = hits.filter((hit) => !recordAllowed(decide, policy, hit.record.scope, hit.record.kind))
1039
+ // 只有“作用域不在范围里”才可能审批;absolute 与 read:false 都不 requestable。
1040
+ const needsApproval = outside.filter((hit) => recordRequestable(decide, policy, hit.record.scope, hit.record.kind))
825
1041
  let verdict
826
1042
  if (needsApproval.length > 0 && level === 'normal') {
827
1043
  verdict = await askOutOfScope(
@@ -861,7 +1077,9 @@ export function memorySearchTool(opts )
861
1077
  // 0.23:被挡住时告诉模型真实原因(绝对限制 / 不可读 / 审批拒绝…),不再假装不存在。
862
1078
  const denied = outside.length - approvedOutside.length
863
1079
  if (denied > 0) {
864
- const reason = withheldReasonFor(policy, verdict, outside.length > 0)
1080
+ const approvedIds = new Set(approvedOutside.map((hit) => hit.record.id))
1081
+ const deniedRecords = outside.filter((hit) => !approvedIds.has(hit.record.id))
1082
+ const reason = withheldReasonFor(decide, policy, deniedRecords.map((hit) => ({ scope: hit.record.scope, kind: hit.record.kind })), verdict)
865
1083
  if (reason !== undefined) result.withheld = { count: denied, reason }
866
1084
  }
867
1085
  if (wantedTopK !== undefined) result.records = result.records.slice(0, wantedTopK)
@@ -906,16 +1124,20 @@ export function memoryForgetTool(opts )
906
1124
  if (args.id && args.query) throw new MemoryToolError('TARGET_AMBIGUOUS', 'provide id or query, not both')
907
1125
  // 没有会话就不判断可见域:护栏只对"本会话的 Agent"生效(与 provider 一致)。
908
1126
  const policy = agent === undefined ? undefined : visibilityPolicy(service, agent)
1127
+ const decide = decisionMaker(service, agent)
909
1128
  const level = policy?.level ?? 'none'
910
1129
  const signal = (exec )?.signal
911
1130
  // ---- 按 id 删除:先查出这条记录在哪个 scope,再按可写范围判断 ----
912
1131
  if (args.id) {
913
1132
  const matches = (service.getByIds?.([args.id]) ?? []).filter((record) => record.id === args.id)
914
- const blocked = matches.filter((record) => !scopeWritable(service, agent, policy, record.scope))
1133
+ const blocked = matches.filter((record) => !scopeWritableBy(decide, service, agent, policy, record.scope))
915
1134
  let approved = false
916
1135
  if (blocked.length > 0) {
917
- // 作用域在范围内但「可写」关掉,或绝对限制下根本不在范围内:直接说明原因。
918
- if (level === 'absolute' || policyRule(policy, blocked[0] .scope) !== undefined) {
1136
+ const decision = decide('write', blocked[0] .scope)
1137
+ if (decision !== undefined) {
1138
+ if (!decision.requestable) throw blockedRecordDecisionError(decision, blocked[0] .scope, args.id)
1139
+ } else if (level === 'absolute' || policyRule(policy, blocked[0] .scope) !== undefined) {
1140
+ // 老 provider 没有授权判定时保持原有纯策略判断。
919
1141
  throw blockedRecordError(policy, blocked[0] .scope, args.id)
920
1142
  }
921
1143
  if (level === 'normal') {
@@ -953,9 +1175,12 @@ export function memoryForgetTool(opts )
953
1175
  }
954
1176
  const scope = resolved.scope ?? readScopes(opts, service, agent)[0]
955
1177
  let approved = false
956
- if (level !== 'none' && scope !== undefined && !scopeWritable(service, agent, policy, scope)) {
957
- // 绝对限制 / 「可写」关掉:直接说明原因,不再静默返回"删了 0 条"。
958
- if (policyRule(policy, scope) !== undefined || level === 'absolute') {
1178
+ if (level !== 'none' && scope !== undefined && !scopeWritableBy(decide, service, agent, policy, scope)) {
1179
+ const decision = decide('write', scope)
1180
+ if (decision !== undefined) {
1181
+ if (!decision.requestable) throw writeDecisionError(decision, scope, 'delete')
1182
+ } else if (policyRule(policy, scope) !== undefined || level === 'absolute') {
1183
+ // 老 provider 没有授权判定时保持原有纯策略判断。
959
1184
  throw scopeWriteBlockedError(policy, scope, 'delete')
960
1185
  }
961
1186
  const verdict = await askOutOfScope(
@@ -1031,6 +1256,7 @@ export function memoryListTool(opts )
1031
1256
  requireDescription(service, agent, args.description)
1032
1257
  const resolved = resolveScope(opts, service, exec, args.scope, 'read')
1033
1258
  const policy = visibilityPolicy(service, agent)
1259
+ const decide = decisionMaker(service, agent)
1034
1260
  const level = policy?.level ?? 'none'
1035
1261
  // level=none 时策略里的 scopes 只是偏好,不参与限制(等价于没有可见域)。
1036
1262
  const visible = policy !== undefined && policy.level !== 'none' ? policy.scopes.map((rule) => rule.scope) : undefined
@@ -1061,9 +1287,9 @@ export function memoryListTool(opts )
1061
1287
  // 多取一些候选,避免范围外记录挤掉范围内结果。
1062
1288
  limit: Math.min(200, Math.max(limit, limit * 2)),
1063
1289
  })
1064
- const inside = raw.filter((record) => recordAllowed(policy, record.scope, record.kind))
1065
- const outside = raw.filter((record) => !recordAllowed(policy, record.scope, record.kind))
1066
- const needsApproval = outside.filter((record) => policyRule(policy, record.scope) === undefined || policyRule(policy, record.scope)?.read !== false)
1290
+ const inside = raw.filter((record) => recordAllowed(decide, policy, record.scope, record.kind))
1291
+ const outside = raw.filter((record) => !recordAllowed(decide, policy, record.scope, record.kind))
1292
+ const needsApproval = outside.filter((record) => recordRequestable(decide, policy, record.scope, record.kind))
1067
1293
  let verdict
1068
1294
  if (needsApproval.length > 0 && level === 'normal') {
1069
1295
  verdict = await askOutOfScope(
@@ -1099,7 +1325,9 @@ export function memoryListTool(opts )
1099
1325
  }))
1100
1326
  const denied = outside.length - approvedOutside.length
1101
1327
  if (denied > 0) {
1102
- const reason = withheldReasonFor(policy, verdict, outside.length > 0)
1328
+ const approvedIdSet = new Set(approvedOutside.map((record) => record.id))
1329
+ const deniedRecords = outside.filter((record) => !approvedIdSet.has(record.id))
1330
+ const reason = withheldReasonFor(decide, policy, deniedRecords.map((record) => ({ scope: record.scope, kind: record.kind })), verdict)
1103
1331
  if (reason !== undefined) withheld = { count: denied, reason }
1104
1332
  }
1105
1333
  // 上下文去重:同版本已经出现过 → 只回 id,正文让 memory_get 按需取。
@@ -1133,6 +1361,130 @@ export function memoryListTool(opts )
1133
1361
  }
1134
1362
  }
1135
1363
 
1364
+
1365
+
1366
+                    
1367
+
1368
+
1369
+
1370
+
1371
+
1372
+                    
1373
+
1374
+
1375
+                
1376
+
1377
+                 
1378
+
1379
+                      
1380
+
1381
+
1382
+
1383
+
1384
+
1385
+             
1386
+
1387
+          
1388
+
1389
+
1390
+
1391
+
1392
+
1393
+ /**
1394
+ * 作用域目录 / 权限申请工具(0.24.0)。
1395
+ *
1396
+ * list:只返回目录元信息与访问状态,**不返回任何记忆正文**;范围外条目的记录数
1397
+ * 也刻意不返回(条数会泄露“有没有内容”)。
1398
+ *
1399
+ * request:只申请**本会话**的授权(默认只读,写权限独立申请)。一次性访问不走这里,
1400
+ * 继续由 memory_* 的隐式审批处理;absolute 下所有申请都会得到 not-requestable。
1401
+ */
1402
+ export function memoryScopesTool(opts ) {
1403
+ return {
1404
+ name: 'memory_scopes',
1405
+ description: 'List memory scopes with their purpose and access status (metadata only, no content), or request session access to out-of-scope scopes. action="request" defaults to read-only and requires a reason; absolute restriction never grants access.',
1406
+ parameters: {
1407
+ action: { type: 'string', enum: ['list', 'request'], description: 'list = 目录;request = 申请范围外作用域的会话权限(默认只读)' },
1408
+ includeOutOfScope: { type: 'boolean', description: 'list:默认 true;false 时只列当前可见域内的作用域。' },
1409
+ limit: { type: 'number', description: 'list:1~200,默认 50' },
1410
+ requests: {
1411
+ type: 'array',
1412
+ description: 'request:要申请的作用域与权限,最多 5 个 scope;permissions 省略 = 只读',
1413
+ items: {
1414
+ type: 'object',
1415
+ properties: {
1416
+ scope: { type: 'string' },
1417
+ permissions: { type: 'array', items: { type: 'string', enum: ['read', 'write'] } },
1418
+ },
1419
+ required: ['scope'],
1420
+ },
1421
+ },
1422
+ reason: { type: 'string', description: 'request:一句话申请理由,展示在审批卡上' },
1423
+ description: { type: 'string', description: DESCRIPTION_PARAM_DESCRIPTION },
1424
+ },
1425
+ async execute(args , exec ) {
1426
+ const service = svc(opts)
1427
+ const agent = agentOf(exec)
1428
+ requireDescription(service, agent, args.description)
1429
+
1430
+ if (args.action === 'request') {
1431
+ if (typeof service.requestScopeGrants !== 'function') {
1432
+ throw new MemoryToolError('SCOPES_UNAVAILABLE', '当前 provider 不支持作用域权限申请(请升级 @restregular/dsh-memory)')
1433
+ }
1434
+ const raw = Array.isArray(args.requests) ? args.requests : []
1435
+ if (raw.length === 0) {
1436
+ throw new MemoryToolError('REQUESTS_REQUIRED', 'action="request" 需要 requests 数组(scope + 可选 permissions)')
1437
+ }
1438
+ if (raw.length > 5) {
1439
+ throw new MemoryToolError('REQUESTS_TOO_MANY', '一次最多申请 5 个作用域;请分批申请')
1440
+ }
1441
+ const requests = raw.map((item) => {
1442
+ const scope = typeof item?.scope === 'string' ? item.scope.trim() : ''
1443
+ if (scope === '') throw new MemoryToolError('SCOPE_INVALID', 'requests[].scope 不能为空')
1444
+ const permissions = Array.isArray(item.permissions)
1445
+ ? [...new Set(item.permissions.filter((permission) => permission === 'read' || permission === 'write'))]
1446
+ : ['read' ]
1447
+ return { scope, permissions: permissions.length > 0 ? permissions : ['read' ] }
1448
+ })
1449
+ const reason = typeof args.reason === 'string' ? args.reason.trim() : ''
1450
+ try {
1451
+ const result = await service.requestScopeGrants(agent, {
1452
+ requests,
1453
+ ...(reason !== '' ? { reason } : {}),
1454
+ ...(args.description !== undefined ? { description: args.description } : {}),
1455
+ ...(exec )?.signal !== undefined
1456
+ ? { signal: (exec ).signal }
1457
+ : {},
1458
+ })
1459
+ return {
1460
+ results: result.results,
1461
+ ...(result.outcome !== undefined ? { outcome: result.outcome } : {}),
1462
+ }
1463
+ } catch (error) {
1464
+ throw toolError(error)
1465
+ }
1466
+ }
1467
+
1468
+ if (typeof service.scopeCatalog !== 'function') {
1469
+ throw new MemoryToolError('SCOPES_UNAVAILABLE', '当前 provider 不支持作用域目录(请升级 @restregular/dsh-memory)')
1470
+ }
1471
+ let all
1472
+ try {
1473
+ all = service.scopeCatalog(agent)
1474
+ } catch (error) {
1475
+ throw toolError(error)
1476
+ }
1477
+ const filtered = args.includeOutOfScope === false ? all.filter((item) => item.inScope) : all
1478
+ const limit = args.limit !== undefined ? Math.min(200, Math.max(1, args.limit)) : 50
1479
+ return {
1480
+ scopes: filtered.slice(0, limit),
1481
+ total: filtered.length,
1482
+ omitted: Math.max(0, filtered.length - limit),
1483
+ }
1484
+ },
1485
+ }
1486
+ }
1487
+
1136
1488
  /** memory_get 可按需取得的字段。id 始终返回,不在此列。 */
1137
1489
  export const GET_FIELDS = [
1138
1490
  'content',
@@ -1146,6 +1498,7 @@ export const GET_FIELDS = [
1146
1498
  'expiresAt',
1147
1499
  'triggers',
1148
1500
  'supersedes',
1501
+ 'initial',
1149
1502
  ]
1150
1503
 
1151
1504
 
@@ -1226,6 +1579,7 @@ function pickGetFields(
1226
1579
  case 'expiresAt': if (record.expiredAt !== undefined) out.expiresAt = record.expiredAt; break
1227
1580
  case 'triggers': if (Array.isArray(record.triggers)) out.triggers = record.triggers; break
1228
1581
  case 'supersedes': if (record.supersedes !== undefined && record.supersedes !== '') out.supersedes = record.supersedes; break
1582
+ case 'initial': if (record.initial === true) out.initial = true; break
1229
1583
  }
1230
1584
  }
1231
1585
  return out
@@ -1262,11 +1616,12 @@ export function memoryGetTool(opts )
1262
1616
  const all = service.getByIds(ids)
1263
1617
  // 可见域是白名单:即使知道 id,也不能直接读别的范围/别的类型的正文。
1264
1618
  const policy = visibilityPolicy(service, agent)
1619
+ const decide = decisionMaker(service, agent)
1265
1620
  const level = policy?.level ?? 'none'
1266
- const inside = all.filter((record) => recordAllowed(policy, record.scope, record.kind))
1267
- const outside = all.filter((record) => !recordAllowed(policy, record.scope, record.kind))
1268
- // read:false 是用户显式关掉的可读状态,审批也不放行;只有"作用域不在范围里"才审批。
1269
- const needsApproval = outside.filter((record) => policyRule(policy, record.scope) === undefined || policyRule(policy, record.scope)?.read !== false)
1621
+ const inside = all.filter((record) => recordAllowed(decide, policy, record.scope, record.kind))
1622
+ const outside = all.filter((record) => !recordAllowed(decide, policy, record.scope, record.kind))
1623
+ // read:false / absolute 都不 requestable;只有"作用域不在范围里"才审批。
1624
+ const needsApproval = outside.filter((record) => recordRequestable(decide, policy, record.scope, record.kind))
1270
1625
  let verdict
1271
1626
  if (needsApproval.length > 0 && level === 'normal') {
1272
1627
  verdict = await askOutOfScope(
@@ -1293,7 +1648,11 @@ export function memoryGetTool(opts )
1293
1648
  const approvedIds = new Set(approvedOutside.map((record) => record.id))
1294
1649
  const found = all.filter((record) => insideIds.has(record.id) || approvedIds.has(record.id))
1295
1650
  const denied = outside.length - approvedOutside.length
1296
- const reason = denied > 0 ? withheldReasonFor(policy, verdict, outside.length > 0) : undefined
1651
+ const approvedIdSet = new Set(approvedOutside.map((record) => record.id))
1652
+ const deniedRecords = outside.filter((record) => !approvedIdSet.has(record.id))
1653
+ const reason = denied > 0
1654
+ ? withheldReasonFor(decide, policy, deniedRecords.map((record) => ({ scope: record.scope, kind: record.kind })), verdict)
1655
+ : undefined
1297
1656
  return {
1298
1657
  records: found.map((r) => pickGetFields(r, fields, chars)),
1299
1658
  fields,
@@ -1316,6 +1675,7 @@ export function memoryTools(opts ) {
1316
1675
  memory_search: memorySearchTool(opts),
1317
1676
  memory_forget: memoryForgetTool(opts),
1318
1677
  memory_list: memoryListTool(opts),
1678
+ memory_scopes: memoryScopesTool(opts),
1319
1679
  memory_get: memoryGetTool(opts),
1320
1680
  }
1321
1681
  }