@restregular/dsh-memory 0.35.2 → 0.35.4

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,19 @@
2
2
 
3
3
  本项目的版本记录。安装 id 与 npm 版本一一对应。
4
4
 
5
+ ## 0.35.4 — 通用钩子 + 自动召回也走 before-inject
6
+
7
+ - **钩子不再必须挂到记忆上**:`memory_hooks` 的 `action:"save"` 新增可选 `ruleId` —— 不传就是**通用钩子**(不挂任何记忆,靠 `scopes` / `kinds` / `phase` 与脚本里的 `ctx` 决定何时自动执行;`scopes:[]`+`kinds:[]` 即对所有记忆生效)。传了则关联到规则记忆(报错带 id、可 memory_get 取全文)。更新时省略 = 保留旧关联。此前创建入口只有 `memory_save.hookCode`(强制关联一条规则),无法建通用钩子。
8
+ - **before-inject 覆盖自动召回**:此前只有规则段、摘要两条注入通道接了注入前解析,每轮按用户问题触发的自动召回没过钩子(三条通道里的漏网之鱼)。现在召回命中在渲染前过 `before-inject`:可返回 `{content}` 改写、 `{drop:true}` 丢弃(被丢的记录以 `reason:'hook'` 计入审计 omitted,不再凭空消失)。会话 id 由 injector 传给 transform;解析失败 = 没解析,记录原样进上下文,钩子坏掉不会吞掉记忆。
9
+ - **技能与文档同步**:`memory-hook-scripts` 补充"钩子一定要挂到记忆上吗"(两种创建方式)与三条注入通道说明。
10
+ - 回归守卫:`inject.test.ts` 加两条(transform 改写/丢弃 + 会话 id 传递、transform 抛错时原样注入),`hooks-tool.test.ts` 加两条(不传 ruleId 建通用钩子、显式 ruleId 关联)。全套 645 tests / 644 pass / 1 skipped。
11
+
12
+ ## 0.35.3 — 钩子否决保存时自动带上关联规则 ID
13
+
14
+ - **问题**:钩子拒绝一条记忆写入时,报错只说「钩子『记忆内容规范(概括句:正文)』判定不符合要求」,模型看不到这条校验代码挂在**哪条规则记忆**上 —— 脚本的 `message` 往往只讲"缺什么",模型想按规则全文改对却无从取起。
15
+ - **修法**:`HookOutcome.hook` 带上 `ruleId`(钩子创建时由 `memory_save.hookCode` 关联的规则记忆 id);`before-save` 否决时报错自动追加一行「关联规则记忆:<完整 id>(用 memory_get("<8位短 id>") 取全文,按规则改好后重试)」。`memory_hooks run` 的判定说明、试跑 outcome 也带上同一个 ruleId。没有关联规则的手动钩子不会凭空造出这一行。
16
+ - 回归守卫:`hooks.test.ts` 加两条(报错带 ruleId + memory_get 提示 / 裸钩子不伪造 ruleId,试跑 outcome 带 ruleId),`bundled-skills.test.ts` 加一条静态守卫。全套 641 tests / 640 pass / 1 skipped。
17
+
5
18
  ## 0.35.2 — 修复「未批准的新脚本无法试跑」:试跑改按 id 精确执行
6
19
 
7
20
  - **问题(再次实机验证发现)**:技能 `memory-hook-scripts` 的上手流程第一步就是「先 `memory_hooks run` 试跑样例,再上线」。但 0.35.0/0.35.1 的 `run` 走的是 `runHooks(phase, ...)`,而 `runHooks` 会在 `HookStore.forRun()` 里过滤掉**未批准**的钩子(审批门禁放在存储层是对的),于是刚保存、还没批准的新脚本试跑时永远报「脚本没有命中这次输入(作用域/类型过滤把它排除了)」—— 实际上是审批门禁挡的,报错还说错了原因。流程直接走不通。
package/README.md CHANGED
@@ -370,9 +370,11 @@ memory_scopes({
370
370
 
371
371
  | 时机 | 触发点 | 能做什么 |
372
372
  | --- | --- | --- |
373
- | `before-save` | `memory_save` 落盘前 | 返回 `{ ok: false, message: '哪里错、怎么改' }` **拒绝这次保存**,理由原样回给模型,它改对后重试 |
373
+ | `before-save` | `memory_save` 落盘前 | 返回 `{ ok: false, message: '哪里错、怎么改' }` **拒绝这次保存**,理由原样回给模型,它改对后重试;报错自动带上关联规则 id |
374
374
  | `after-save` | 落盘后 | 只观察 / 附注,不改结果、不阻断 |
375
- | `before-inject` | 进入上下文前 | 返回 `{ content: '改写后' }` 改写正文,`{ drop: true }` 丢弃整条 |
375
+ | `before-inject` | 进入上下文前 | 返回 `{ content: '改写后' }` 改写正文,`{ drop: true }` 丢弃整条。覆盖**三条注入通道**:规则段、摘要、每轮自动召回 |
376
+
377
+ 钩子**不必挂在记忆上**:随 `memory_save.hookCode` 保存会关联到那条规则(记 `ruleId`);用 `memory_hooks` 的 `action:"save"` 且不传 `ruleId` 则建成**通用钩子**,靠 `scopes` / `kinds` / `phase` 与脚本里的 `ctx` 决定何时自动执行。代码实际按作用域 + 类型匹配触发,`ruleId` 只作关联标注。
376
378
 
377
379
  随规则一起登记(`memory_save` 的 `hookCode` / `hookPhase`):
378
380
 
@@ -242,7 +242,24 @@ export function apply(ctx , config = {}) {
242
242
  }
243
243
  const impressionCfg = () => {
244
244
  const settings = settingsOf().impression
245
- return { impression: settings.enabled, chars: settings.chars }
245
+ return {
246
+ impression: settings.enabled,
247
+ chars: settings.chars,
248
+ // 0.35.4:自动召回也走 before-inject 钩子 —— 之前只有规则段与摘要接了,
249
+ // 每轮按用户问题召回的正文没过钩子,是三个注入通道里的漏网之鱼。
250
+ // sessionId 由 injector 在渲染时传入(注入半边没有 agent 对象)。
251
+ transform: (records, sid) => {
252
+ const mem = ctx.get('memory')
253
+ if (records.length === 0 || typeof mem?.parseForInject !== 'function') return { records }
254
+ try {
255
+ const parsed = mem.parseForInject(records, sid)
256
+ return { records: parsed.records, droppedIds: new Set(parsed.changed.filter((c) => c.option === 'dropped').map((c) => c.id)) }
257
+ } catch {
258
+ // 解析失败 = 没解析:记录原样进上下文,不能因为钩子坏掉就少注入记忆。
259
+ return { records }
260
+ }
261
+ },
262
+ }
246
263
  }
247
264
 
248
265
  const extraScopes = normalizeExtraScopes(config.extraScopes ?? [])
@@ -210,11 +210,19 @@ export function hasRecallMessage(
210
210
 
211
211
            
212
212
 
213
+                       
214
+
215
+
216
+                   
217
+                        
218
+                        
219
+
220
+
213
221
 
214
222
 
215
223
 
216
224
 
217
-
225
+
218
226
 
219
227
 
220
228
 
@@ -232,6 +240,24 @@ export function renderRecallBlock(
232
240
  options = {},
233
241
  ) {
234
242
  if (hits.length === 0) return null
243
+ // 0.35.4:before-inject 钩子先解析召回记录 —— 可改写正文或丢弃整条。
244
+ // 丢弃的要计入 omitted(审计要能解释"为什么某条没进上下文")。
245
+ let effectiveHits = hits
246
+ const droppedIds = new Set ()
247
+ if (options.transform !== undefined) {
248
+ try {
249
+ const transformed = options.transform(hits.map((h) => h.record), options.sessionId)
250
+ const byId = new Map(transformed.records.map((record) => [record.id, record]))
251
+ effectiveHits = hits
252
+ .filter((h) => byId.has(h.record.id))
253
+ .map((h) => ({ ...h, record: byId.get(h.record.id) }))
254
+ for (const id of transformed.droppedIds ?? []) droppedIds.add(id)
255
+ // 变换后没给 droppedIds 但记录变少了:按差集兜底。
256
+ if (transformed.droppedIds === undefined) {
257
+ for (const h of hits) if (!byId.has(h.record.id)) droppedIds.add(h.record.id)
258
+ }
259
+ } catch { /* 解析失败 = 没解析:记录原样进入上下文 */ }
260
+ }
235
261
  const impression = options.impression === true
236
262
  const chars = impression ? (options.chars ?? 120) : 300
237
263
  const header = impression
@@ -242,7 +268,11 @@ export function renderRecallBlock(
242
268
  const ids = []
243
269
  const omitted = []
244
270
  let budgetExhausted = false
245
- for (const [index, h] of hits.entries()) {
271
+ // 被钩子丢弃的记录:审计里要给出原因,不能凭空消失。
272
+ for (const h of hits) {
273
+ if (droppedIds.has(h.record.id)) omitted.push({ id: h.record.id, reason: 'hook' })
274
+ }
275
+ for (const [index, h] of effectiveHits.entries()) {
246
276
  if (index >= cfg.topK) {
247
277
  omitted.push({ id: h.record.id, reason: 'top_k' })
248
278
  continue
@@ -404,7 +434,8 @@ export class MemoryInjector {
404
434
  const freshIds = new Set(fresh.map((record) => record.id))
405
435
  const freshHits = candidates.filter((hit) => freshIds.has(hit.record.id))
406
436
  const optionsForRender = typeof this.renderOptions === 'function' ? this.renderOptions() : this.renderOptions
407
- const block = renderRecallBlock(freshHits, cfg, optionsForRender)
437
+ // 0.35.4:把会话 id 传给 transform(before-inject 钩子按会话判断时用)。
438
+ const block = renderRecallBlock(freshHits, cfg, { ...optionsForRender, sessionId })
408
439
  const base = {
409
440
  ids: [], candidates: candidates.length, dedupSkipped: deduplicated.length, updated, omitted: [], query,
410
441
  // 全部候选都被去重时 block 为 null;把 id 留在结果里,审计才能解释"跳过了哪条"。
@@ -118,7 +118,8 @@ const PHASE_ENTRY = {
118
118
 
119
119
  /** 单个钩子的运行结果。 */
120
120
 
121
-
121
+                                  
122
+
122
123
                        
123
124
 
124
125
             
@@ -561,7 +562,12 @@ export function runHooks(
561
562
  const result = runHookCode(hook.code, phase, input, settings)
562
563
  const crashed = result.error !== undefined
563
564
  const outcome = {
564
- hook: { id: hook.id, name: hook.name, phase },
565
+ hook: {
566
+ id: hook.id,
567
+ name: hook.name,
568
+ phase,
569
+ ...(hook.ruleId !== undefined ? { ruleId: hook.ruleId } : {}),
570
+ },
565
571
  // 崩溃时 ok 恒 true —— 调用方据此"不阻断"。
566
572
  ok: crashed ? true : result.ok,
567
573
  durationMs: Date.now() - started,
@@ -1071,7 +1071,12 @@ export class LocalMemoryService {
1071
1071
  const result = runHookCode(hook.code, hook.phase, input, this.hookSettings())
1072
1072
  const crashed = result.error !== undefined
1073
1073
  return [{
1074
- hook: { id: hook.id, name: hook.name, phase: hook.phase },
1074
+ hook: {
1075
+ id: hook.id,
1076
+ name: hook.name,
1077
+ phase: hook.phase,
1078
+ ...(hook.ruleId !== undefined ? { ruleId: hook.ruleId } : {}),
1079
+ },
1075
1080
  ok: crashed ? true : result.ok,
1076
1081
  durationMs: Date.now() - started,
1077
1082
  ...(result.message !== undefined ? { message: result.message } : {}),
@@ -3379,9 +3384,16 @@ export class LocalMemoryService {
3379
3384
  const veto = outcomes.find((outcome) => outcome.error === undefined && !outcome.ok)
3380
3385
  if (veto !== undefined) {
3381
3386
  const why = veto.message !== undefined && veto.message !== '' ? veto.message : '内容不符合规则记忆的要求'
3387
+ // 0.35.3:把关联的规则记忆 id 自动带进报错。钩子只是规则的执行体,
3388
+ // 模型看到"哪个校验器拒了"还不够 —— 它要能立刻取规则全文才能改对,
3389
+ // 否则只能靠脚本 message 里那几句话猜。
3390
+ const ruleId = veto.hook.ruleId
3391
+ const ruleLine = ruleId !== undefined && ruleId !== ''
3392
+ ? `\n关联规则记忆:${ruleId}(用 memory_get("${ruleId.slice(0, 8)}") 取全文,按规则改好后重试)。`
3393
+ : ''
3382
3394
  throw memoryError(
3383
3395
  'HOOK_REJECTED',
3384
- `记忆未保存:钩子「${veto.hook.name}」判定不符合要求 —— ${why}\n`
3396
+ `记忆未保存:钩子「${veto.hook.name}」判定不符合要求 —— ${why}${ruleLine}\n`
3385
3397
  + '按提示改好 content 后重新调用 memory_save(这不是权限问题,不需要审批)。',
3386
3398
  )
3387
3399
  }
@@ -370,7 +370,8 @@ import { canonicalWorkspacePath, defaultScopeDescription, normalizeScopeInput, r
370
370
 
371
371
  /** 一次钩子运行的结果(试跑与真实运行同形)。 */
372
372
 
373
-
373
+                   
374
+
374
375
 
375
376
 
376
377
 
@@ -2309,7 +2310,12 @@ export function memoryBlockTool(opts )
2309
2310
                         
2310
2311
 
2311
2312
 
2312
-
2313
+
2314
+                                    
2315
+                                   
2316
+             
2317
+
2318
+
2313
2319
                          
2314
2320
 
2315
2321
                          
@@ -2373,6 +2379,11 @@ export function memoryHooksTool(opts )
2373
2379
  description: '运行时机;省略 = 更新时沿用旧值,新建默认 before-save。',
2374
2380
  },
2375
2381
  name: { type: 'string', description: '显示名(面板与审批卡用)' },
2382
+ ruleId: {
2383
+ type: 'string',
2384
+ description: '可选:把钩子关联到一条规则记忆(报错时带 id,可用 memory_get 取全文)。'
2385
+ + '**省略 = 通用钩子**(不挂任何记忆,靠 scopes/kinds/phase 与脚本里的 ctx 决定何时自动执行)。更新时省略 = 保留旧关联。',
2386
+ },
2376
2387
  scopes: { type: 'array', items: { type: 'string' }, description: '适用作用域键;省略 = 全部适用(更新时保留旧值)' },
2377
2388
  kinds: { type: 'array', items: { type: 'string' }, description: '适用记忆类型(fact/rule/...);省略 = 全部适用' },
2378
2389
  content: { type: 'string', description: 'run 试跑用的正文(只跑脚本,不写记忆)' },
@@ -2425,7 +2436,10 @@ export function memoryHooksTool(opts )
2425
2436
  ...(args.kinds !== undefined ? { kinds: args.kinds.map(String) } : { kinds: existing?.kinds ?? [] }),
2426
2437
  ...(args.description !== undefined ? { description: args.description } : {}),
2427
2438
  createdBy: 'agent',
2428
- ...(existing?.ruleId !== undefined ? { ruleId: existing.ruleId } : {}),
2439
+ // 0.35.4:显式给了就更新;否则沿用旧关联;新建时省略 = 通用钩子(无 ruleId)。
2440
+ ...(args.ruleId !== undefined
2441
+ ? { ruleId: args.ruleId }
2442
+ : existing?.ruleId !== undefined ? { ruleId: existing.ruleId } : {}),
2429
2443
  })
2430
2444
  } catch (error) {
2431
2445
  throw toolError(error)
@@ -2536,13 +2550,16 @@ export function memoryHooksTool(opts )
2536
2550
  }
2537
2551
  const mine = service.runHookTrial(hook.id, input)
2538
2552
  const verdict = mine[0]
2553
+ const ruleRef = verdict?.hook.ruleId !== undefined && verdict.hook.ruleId !== ''
2554
+ ? `(关联规则记忆 ${verdict.hook.ruleId},可用 memory_get 取全文)`
2555
+ : ''
2539
2556
  const note = verdict === undefined
2540
2557
  ? '脚本没有命中这次输入(作用域/类型过滤把它排除了)。'
2541
2558
  : verdict.error !== undefined
2542
2559
  ? `脚本运行失败:${verdict.error}`
2543
2560
  : verdict.ok
2544
- ? '脚本判定:通过。'
2545
- : `脚本判定:不通过 —— ${verdict.message ?? '(脚本没给 message)'}`
2561
+ ? `脚本判定:通过。${ruleRef}`
2562
+ : `脚本判定:不通过 —— ${verdict.message ?? '(脚本没给 message)'}${ruleRef}`
2546
2563
  return { action, hooks: [withApproval(hook)], outcomes: mine, note }
2547
2564
  },
2548
2565
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@restregular/dsh-memory",
3
- "version": "0.35.2",
3
+ "version": "0.35.4",
4
4
  "description": "DeepSeek Harness 记忆系统(单包单入口):JSONL 存储 + 本地向量检索(BGE-M3)+ 五个模型工具 + 自动召回注入 + 管理面板。",
5
5
  "icon": "./icon.svg",
6
6
  "type": "module",
@@ -19,8 +19,19 @@ description: "Use when writing or editing the executable script that rides along
19
19
  | `after-save` | 记录已经落盘**之后** | ❌ 只能附注 | 否 |
20
20
  | `before-inject` | 记忆即将进入上下文**之前** | ✅(`drop:true` 丢弃整条) | ✅ 返回 `{content}` 改写 |
21
21
 
22
+ `before-inject` 覆盖**三条注入通道**:系统提示的规则段、会话第一步的摘要、以及每轮按用户问题触发的自动召回。所以"改写/丢弃"对模型实际读到的所有记忆都生效。
23
+
22
24
  默认是 `before-save`。绝大多数"规范类"规则都用它。
23
25
 
26
+ ## 钩子一定要挂到记忆上吗?
27
+
28
+ **不用**。两种创建方式:
29
+
30
+ - **随规则保存**(`memory_save` 带 `hookCode`):钩子关联到那条规则记忆(记下 `ruleId`),校验失败时报错会自动带上规则 id,可用 `memory_get` 取全文。
31
+ - **独立通用钩子**(`memory_hooks` 的 `action:"save"`,**不传 `ruleId`**):不挂任何记忆,靠 `scopes` / `kinds` / `phase` 与脚本里的 `ctx` 决定何时自动执行。例:`scopes:[]` + `kinds:[]` = 对所有记忆生效的通用校验器。
32
+
33
+ 代码实际是按 `scopes`(作用域)+ `kinds`(记忆类型)匹配来触发的,`ruleId` 只是关联标注、不参与匹配。所以同一段代码可以只管某个项目、只管 `rule`、或管全部。
34
+
24
35
  ## 写一个脚本
25
36
 
26
37
  代码是**模块体**:里面定义一个入口函数即可,不需要 `export`,也不要写 `require`。