@restregular/dsh-memory 0.35.4 → 0.36.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/CHANGELOG.md CHANGED
@@ -2,6 +2,14 @@
2
2
 
3
3
  本项目的版本记录。安装 id 与 npm 版本一一对应。
4
4
 
5
+ ## 0.36.0 — supersedes 支持跨作用域修正,且必须显式带 scope
6
+
7
+ - **跨作用域修正**:此前 `memory_save.supersedes` 的旧记录按 id 精确查找时**只查新记录写入的那一个 scope**,旧记录在别的作用域一律报 `SUPERSEDES_UNKNOWN`(且文案与"id 不存在"完全一样)。现在改成跨全部作用域按完整 id 查找(`findById`):新记录可以落在任意作用域去修正另一作用域里的旧记录(project / global / session / 自定义均可)。配套把"已修正/退役"标记也改成全局收集 —— `search` / `listSync` / 自动召回的 `excludedIds` 不再只看当前搜索的 scopes,否则 global 里的修正版挡不住 project 里的旧记录。
8
+ - **必须显式带 scope**:带 `supersedes` 时省略 `scope`(依赖默认作用域)一律拒绝(`SUPERSEDES_SCOPE_REQUIRED`),不静默落到默认作用域造成"修错地方";`supersedes` / `scope` 两个参数的说明与常驻策略段都写清这条口径。
9
+ - **写权限硬门槛**:带 `supersedes` 时当前会话必须对目标作用域**已有写权限**,不足直接拒绝(`SUPERSEDES_SCOPE_NOT_WRITABLE`),不走范围外审批 —— 旧实现会把 `SCOPE_NOT_IN_RANGE` 误报成 `VISIBILITY_ABSOLUTE`。
10
+ - **返回提示统一带目标作用域 key**:所有 `memory_save` 的返回文案新增一行「保存到的目标作用域 key:<scope>」;`supersedes` 场景再补一条修正关系(含旧记录所在作用域)。返回值同时新增 `supersedes:{id,scope?}` 字段,文案仍以「已保存记忆 <uuid> @ <scope>」开头,`memorySaveResultIds` 按 UUID 抽取不受影响。
11
+ - 回归守卫:`service.test.ts` 加跨作用域修正与全局退役用例,`access.test.ts` 加缺 scope / 无写权限 / 返回值三个用例,`tools.test.ts` 与 `policy.test.ts` 锁住参数说明与常驻策略段,`apply-registration.test.ts` 静态锁住返回提示。全套 62 个测试文件在受限沙箱内逐文件跑通(0 失败)。
12
+
5
13
  ## 0.35.4 — 通用钩子 + 自动召回也走 before-inject
6
14
 
7
15
  - **钩子不再必须挂到记忆上**:`memory_hooks` 的 `action:"save"` 新增可选 `ruleId` —— 不传就是**通用钩子**(不挂任何记忆,靠 `scopes` / `kinds` / `phase` 与脚本里的 `ctx` 决定何时自动执行;`scopes:[]`+`kinds:[]` 即对所有记忆生效)。传了则关联到规则记忆(报错带 id、可 memory_get 取全文)。更新时省略 = 保留旧关联。此前创建入口只有 `memory_save.hookCode`(强制关联一条规则),无法建通用钩子。
@@ -552,9 +552,11 @@ export function apply(ctx , config = {}) {
552
552
  procedureTools.set(sessionId, recent)
553
553
  }
554
554
 
555
- const excludedIds = (memory , scopes ) => {
555
+ const excludedIds = (memory , _scopes ) => {
556
556
  try {
557
- return new Set(memory.supersededIds?.(scopes === undefined ? undefined : [...scopes]) ?? [])
557
+ // 0.36.0:supersedes 支持跨作用域,修正版可能不在本次注入的 scopes 里;
558
+ // 退役 id 必须扫全部 scope(省略参数),否则 global 里的修正版挡不住 project 旧记录。
559
+ return new Set(memory.supersededIds?.() ?? [])
558
560
  } catch {
559
561
  return new Set()
560
562
  }
@@ -18,6 +18,8 @@ memory_search 只返回印象(ID、作用域、类型、标签和少量摘要
18
18
 
19
19
  新建自定义作用域时,memory_save 必须带 scopeDescription(一句话用途);可选带 scopeRule 写一条初始规则。已有作用域带上 scopeDescription 表示更新用途,不会写初始记忆。
20
20
 
21
+ 用 memory_save 的 supersedes 修正 / 替换旧记忆时:**必须显式带 scope 参数**(新记录要保存到的目标作用域 key),省略或依赖默认作用域一律拒绝;目标旧记录按完整 id 跨作用域查找,可以不在同一作用域,但当前会话必须对目标作用域已有写权限(不足直接拒绝,不会走范围外审批)。supersedes 只传完整 id(36 位 UUID);返回值里带「保存到的目标作用域 key」与修正关系。
22
+
21
23
  作用域的**用途**和**别名**可以改(用户也能在面板「记录 → 作用域」里改):memory_scopes({ action: "edit", scope, scopeDescription?, scopeName? }) —— scopeDescription 是那句用途(空串 = 清空,回退到按类型的默认描述),scopeName 是别名(空串 = 移除;只影响显示与引用,不改作用域键;项目 / 自定义作用域支持,global / session 不支持)。两者至少给一个,且需要该作用域可写(范围外先用 action="request" 申请写权限)。把用途写清楚,后续检索的「范围外清单」会直接告诉接手的人这个域是干什么的。
22
24
 
23
25
  同一会话里已经出现过的记忆,memory_search / memory_list 只回 ID 并注明“摘要因上下文去重被省略”;那不是没找到,需要正文时直接用 memory_get 取。
@@ -1292,7 +1292,10 @@ export class LocalMemoryService {
1292
1292
  const s = this.store.peek(scope)
1293
1293
  if (s) stores.push(s)
1294
1294
  }
1295
- const retired = input.includeSuperseded ? new Set () : new Set(this.supersededIds(wanted))
1295
+ // 0.36.0:supersedes 支持跨作用域,所以退役标记也必须跨作用域收集 ——
1296
+ // 一条落在 global 的修正版要能让 project 里的旧记录退出检索/注入。
1297
+ // scope 参数只用于过滤"要枚举哪些记录",不再限制"从哪些 scope 收集修正关系"。
1298
+ const retired = input.includeSuperseded ? new Set () : new Set(this.supersededIds())
1296
1299
  const now = Date.now()
1297
1300
  const out = []
1298
1301
  for (const s of stores) {
@@ -3294,8 +3297,12 @@ export class LocalMemoryService {
3294
3297
  if (content.length > this.cfg.maxRecordChars) {
3295
3298
  throw memoryError('CONTENT_TOO_LONG', `content exceeds ${this.cfg.maxRecordChars} chars`)
3296
3299
  }
3297
- if (input.supersedes && !this.store.scope(scope).records.get(input.supersedes)) {
3298
- throw memoryError('SUPERSEDES_UNKNOWN', `supersedes target ${input.supersedes} not found in ${scope}`)
3300
+ // 0.36.0:supersedes 的旧记录按**完整 id 跨作用域**查找 —— 新记录可以落在任意
3301
+ // 作用域去修正另一作用域里的旧记录(project / global / session / 自定义均可)。
3302
+ // 之前这里用 `this.store.scope(scope).records.get(id)` 只查新记录自己的 scope,
3303
+ // 跨作用域一律报 SUPERSEDES_UNKNOWN;findById 会扫描全部已加载/已发现的 scope。
3304
+ if (input.supersedes && !this.findById(input.supersedes)) {
3305
+ throw memoryError('SUPERSEDES_UNKNOWN', `supersedes target ${input.supersedes} not found in any scope`)
3299
3306
  }
3300
3307
  // 状态型记忆(state)默认带 TTL:写入时算一次绝对 expiresAt,读取时只比较时间。
3301
3308
  // 显式 expiresAt 优先;ttlMs 对任何 kind 都生效(便于测试/特殊用途)。
@@ -3618,12 +3625,9 @@ export class LocalMemoryService {
3618
3625
 
3619
3626
  // 退役(superseded)记录默认不参与召回:它们只是被新记录修正过的历史版本,
3620
3627
  // 继续返回会让模型拿旧结论当现行事实。memory_get(id)/面板历史仍可直接取。
3621
- const retired = new Set ()
3622
- for (const { store } of stores) {
3623
- for (const record of store.records.values()) {
3624
- if (record.supersedes) retired.add(record.supersedes)
3625
- }
3626
- }
3628
+ // 0.36.0:跨作用域修正后,修正版可能不在本次搜索的 scopes 里(例如修正版落
3629
+ // global、旧记录在 project),所以退役 id 必须扫全部 scope,不能只看 stores。
3630
+ const retired = new Set (this.supersededIds())
3627
3631
 
3628
3632
  // --- channel 1: lexical recall, scored per scope with local IDF ---
3629
3633
 
@@ -141,10 +141,16 @@ export function apply(ctx , config = {}) {
141
141
  const head = value.deduped
142
142
  ? `已更新既有记忆(内容相同,去重):${value.id} @ ${renderScope(value.scope, agent)}`
143
143
  : `已保存记忆 ${value.id} @ ${renderScope(value.scope, agent)}`
144
- // 0.35.2:带 hookCode 时把钩子的登记 / 审批结局回给模型 —— 否则它不知道
145
- // 脚本到底挂没挂上、是不是还在等批准(未批准 = 不会运行)。
144
+ // 0.36.0:所有 memory_save 返回统一带上保存到的目标作用域 key;用 supersedes
145
+ // 修正旧记忆时额外说明修正关系(旧记录所在作用域可不同)。文案仍以
146
+ // 「已保存记忆 <uuid> @ <scope>」开头,signals.ts 按 UUID 抽取不受影响。
147
+ const scopeKeyLine = `保存到的目标作用域 key:${value.scope}`
148
+ const correctionLine = value.supersedes === undefined
149
+ ? ''
150
+ : `\n已用本条修正旧记忆 ${value.supersedes.id}${value.supersedes.scope !== undefined ? `(旧记录在 ${value.supersedes.scope})` : ''}`
151
+ const tail = `\n${scopeKeyLine}${correctionLine}`
146
152
  const hook = value.hook
147
- if (hook === undefined) return head
153
+ if (hook === undefined) return `${head}${tail}`
148
154
  const approvalText = {
149
155
  approved: '已获批准,会按设定时机运行',
150
156
  rejected: '用户拒绝批准,**不会运行**(改脚本或让用户批准后才生效)',
@@ -156,7 +162,7 @@ export function apply(ctx , config = {}) {
156
162
  const state = hook.approval.startsWith('save-failed')
157
163
  ? `登记失败:${hook.approval.slice('save-failed: '.length)}`
158
164
  : approvalText[hook.approval] ?? hook.approval
159
- return `${head}\n随附规则代码 ${hook.id !== '' ? `${hook.id} ` : ''}(${hook.phase}):${state}`
165
+ return `${head}${tail}\n随附规则代码 ${hook.id !== '' ? `${hook.id} ` : ''}(${hook.phase}):${state}`
160
166
  })
161
167
 
162
168
  register(tools.memory_search, (value, _args, exec) => {
@@ -645,6 +645,19 @@ function outOfScopeReason(
645
645
  */
646
646
  const SUPERSEDES_PARAM_DESCRIPTION =
647
647
  '被这条新记忆修正 / 替换掉的旧记录 id。必须传**完整 id**(36 位 UUID),不能传 memory_search / memory_list / 摘要 / 规则索引里显示的 8 位短 id;手头只有短 id 时先用 memory_get 取回 —— 它结果里每段首行的 [id] 就是完整 id。旧记录会被标记为「已修正」,默认不再出现在检索、规则和自动召回里,但 memory_get 仍能查到。'
648
+ + '传了 supersedes 时**必须显式带 scope 参数**(不接受省略 / 默认作用域):scope 是新记录要保存到的目标作用域,本会话必须对它拥有写权限;跨作用域修正(旧记录在别的作用域)现在支持,但目标作用域必须写权限,否则直接拒绝,不做审批。'
649
+
650
+ /** 带 supersedes 时必须显式写 scope:拒绝静默落到默认作用域造成“修错地方”。 */
651
+ function requireScopeForSupersedes(args , explicit ) {
652
+ if (args.supersedes === undefined || args.supersedes === '') return
653
+ const raw = args.scope?.trim()
654
+ if (explicit === undefined || raw === undefined || raw === '') {
655
+ throw new MemoryToolError(
656
+ 'SUPERSEDES_SCOPE_REQUIRED',
657
+ '用 supersedes 修正旧记忆时必须显式传 scope 参数(新记录要保存到的目标作用域 key),不能省略、不能依赖默认作用域;否则拒绝保存。',
658
+ )
659
+ }
660
+ }
648
661
 
649
662
  /** memory_* 的 description 参数说明(模型可见)。 */
650
663
  const DESCRIPTION_PARAM_DESCRIPTION =
@@ -956,10 +969,13 @@ function resolveScope(
956
969
 
957
970
 
958
971
 
972
+                                           
959
973
 
960
974
                     
961
975
 
962
976
 
977
+                             
978
+
963
979
                                    
964
980
 
965
981
 
@@ -1047,6 +1063,11 @@ export function memorySaveTool(opts )
1047
1063
  explicit = resolved
1048
1064
  }
1049
1065
 
1066
+ // 0.36.0:带 supersedes 时 scope 必须显式给出(见 requireScopeForSupersedes),
1067
+ // 且本会话必须对目标作用域已有写权限 —— 不触发范围外审批,权限不足直接拒绝。
1068
+ requireScopeForSupersedes(args, explicit)
1069
+ const isSupersedes = args.supersedes !== undefined && args.supersedes !== ''
1070
+
1050
1071
  // 写入护栏(0.20.0 / 0.23.0):write 开关与范围等级分开判断。
1051
1072
  // - 作用域在范围内但「可写」关掉 → 直接拒绝并说明开关;
1052
1073
  // - absolute 且作用域不在范围内 → 直接拒绝并说明绝对限制;
@@ -1058,7 +1079,16 @@ export function memorySaveTool(opts )
1058
1079
  const level = policy?.level ?? 'none'
1059
1080
  const target = explicit ?? (typeof service.resolveWriteScope === 'function' ? service.resolveWriteScope(agent) : undefined)
1060
1081
  let approved = false
1061
- if (level !== 'none' && target !== undefined && !scopeWritableBy(decide, service, agent, policy, target)) {
1082
+ if (isSupersedes && level !== 'none' && target !== undefined && !scopeWritableBy(decide, service, agent, policy, target)) {
1083
+ // supersedes 是"改旧记忆"的写操作:必须已有写权限,不走范围外审批。
1084
+ // 不论拒绝原因是绝对限制 / 只读 / 范围外,统一用一个 dedicated 错误码与文案,
1085
+ // 避免把 "SCOPE_NOT_IN_RANGE" 误报成 VISIBILITY_ABSOLUTE(见 0.36.0)。
1086
+ throw new MemoryToolError(
1087
+ 'SUPERSEDES_SCOPE_NOT_WRITABLE',
1088
+ `用 supersedes 修正旧记忆要求当前会话对目标作用域 ${target} 已有写权限(作用域不在本会话可写范围内),本次保存没有执行。请先让用户授予该作用域写权限,或改用本会话可写的作用域。`,
1089
+ )
1090
+ }
1091
+ if (!isSupersedes && level !== 'none' && target !== undefined && !scopeWritableBy(decide, service, agent, policy, target)) {
1062
1092
  const decision = decide('write', target)
1063
1093
  if (decision !== undefined) {
1064
1094
  // provider 已经给出统一判定:不可申请就直接讲原因(absolute / 关闭 / 只读)。
@@ -1131,11 +1161,19 @@ export function memorySaveTool(opts )
1131
1161
  description: args.description,
1132
1162
  })
1133
1163
  }
1164
+ let oldScope
1165
+ if (isSupersedes) {
1166
+ try {
1167
+ const hit = (await service.getByIds?.([args.supersedes ]))?.[0]
1168
+ oldScope = hit?.scope
1169
+ } catch { /* 取不到旧记录作用域只影响提示,不影响保存成功 */ }
1170
+ }
1134
1171
  return {
1135
1172
  id: record.id,
1136
1173
  scope: record.scope,
1137
1174
  ...(alias !== undefined ? { scopeName: alias } : {}),
1138
1175
  deduped: false,
1176
+ ...(isSupersedes ? { supersedes: { id: args.supersedes , ...(oldScope !== undefined ? { scope: oldScope } : {}) } } : {}),
1139
1177
  ...(hookInfo !== undefined ? { hook: hookInfo } : {}),
1140
1178
  }
1141
1179
  } catch (error) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@restregular/dsh-memory",
3
- "version": "0.35.4",
3
+ "version": "0.36.0",
4
4
  "description": "DeepSeek Harness 记忆系统(单包单入口):JSONL 存储 + 本地向量检索(BGE-M3)+ 五个模型工具 + 自动召回注入 + 管理面板。",
5
5
  "icon": "./icon.svg",
6
6
  "type": "module",