@restregular/dsh-memory 0.34.0 → 0.35.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.
@@ -0,0 +1,142 @@
1
+ ---
2
+ name: memory-hook-scripts
3
+ description: "Use when writing or editing the executable script that rides along with a memory rule — memory_save's hookCode / hookPhase parameters, or the memory_hooks tool (save / get / run / approve). Covers the three run phases, the sandbox API, the return contract, and ready-made validators for the 「概括:正文」 format and similar content rules."
4
+ ---
5
+
6
+ # Memory hook scripts
7
+
8
+ 一段规则可以带一段脚本,插件在固定时机替你运行它。这让"能写成检查的规则"从
9
+ **写给模型看的话**变成**代码强制**——模型看漏了也不会漏校验。
10
+
11
+ 脚本存在 `hooks.json`,**不进记忆检索**:`memory_search` / `memory_list` / 摘要 /
12
+ 自动召回都看不到代码,只有 `memory_hooks` 和面板能读。
13
+
14
+ ## 三个时机
15
+
16
+ | phase | 什么时候跑 | 能否否决 | 能改正文吗 |
17
+ |---|---|---|---|
18
+ | `before-save` | `memory_save` 落盘**之前** | ✅ 返回 `{ok:false}` 直接拒绝这次保存 | 否 |
19
+ | `after-save` | 记录已经落盘**之后** | ❌ 只能附注 | 否 |
20
+ | `before-inject` | 记忆即将进入上下文**之前** | ✅(`drop:true` 丢弃整条) | ✅ 返回 `{content}` 改写 |
21
+
22
+ 默认是 `before-save`。绝大多数"规范类"规则都用它。
23
+
24
+ ## 写一个脚本
25
+
26
+ 代码是**模块体**:里面定义一个入口函数即可,不需要 `export`,也不要写 `require`。
27
+
28
+ 入口函数名按时机取:
29
+
30
+ - `before-save` → `function verify(memory, ctx)`
31
+ - `after-save` → `function observe(memory, ctx)`
32
+ - `before-inject` → `function parse(memory, ctx)`
33
+
34
+ (`main` 是所有时机的兜底名。)
35
+
36
+ ```js
37
+ // 记忆内容规范:必须是「概括句 + : + 正文」
38
+ function verify(memory) {
39
+ const text = memory.content
40
+ if (!text.includes(':')) {
41
+ return { ok: false, message: '记忆内容必须是「概括句:正文」格式,缺少全角冒号「:」' }
42
+ }
43
+ const head = text.slice(0, text.indexOf(':')).trim()
44
+ if (head.length === 0) {
45
+ return { ok: false, message: '冒号前必须是能独立看懂的概括句,现在是空的' }
46
+ }
47
+ if (head.length > 60) {
48
+ return { ok: false, message: '概括句太长(' + head.length + ' 字),控制在 60 字以内' }
49
+ }
50
+ return { ok: true }
51
+ }
52
+ ```
53
+
54
+ ## 能拿到什么
55
+
56
+ `memory` 是一条记忆的**纯数据拷贝**(改了也不影响真实记录):
57
+
58
+ ```js
59
+ {
60
+ id, scope, kind, content, tags: [], importance,
61
+ triggers, createdAt, updatedAt, expiresAt, supersedes, initial
62
+ }
63
+ ```
64
+
65
+ `ctx` 描述这次调用:
66
+
67
+ ```js
68
+ { phase, tool, sessionId, description, now }
69
+ ```
70
+
71
+ `tool` 是触发者(`'memory_save'` / `'memory_hooks'` / `'inject'`),可以据此分支:
72
+
73
+ ```js
74
+ function verify(memory, ctx) {
75
+ if (ctx.tool !== 'memory_save') return true // 只拦显式保存
76
+ ...
77
+ }
78
+ ```
79
+
80
+ ## 返回什么
81
+
82
+ | 返回 | 含义 |
83
+ |---|---|
84
+ | `true` / `undefined` | 通过 |
85
+ | `false` | 不通过(没有说明,模型只能看到"未通过") |
86
+ | `{ ok: true }` | 通过 |
87
+ | `{ ok: false, message: '…' }` | 不通过,`message` 会**原样回给模型**——写清楚"哪里错、怎么改" |
88
+ | `'一段话'` | 不通过,这段话就是理由 |
89
+ | `{ ok: true, message: '…' }` | 通过,并把这句话附在工具结果里 |
90
+ | `{ content: '新正文' }` | 改写正文(`before-inject` / `after-save` 生效) |
91
+ | `{ drop: true }` | 整条丢弃(`before-inject`) |
92
+
93
+ **`message` 是写给模型看的**。它决定了模型下一次能不能自己改对,所以要说
94
+ "缺什么、应该怎样",而不是"格式错误"。
95
+
96
+ ## 沙箱里有什么
97
+
98
+ 可以:`JSON` `Math` `Date` `String` `Number` `Boolean` `Array` `Object` `RegExp`
99
+ `Map` `Set` `Error` `parseInt` `parseFloat` `isNaN` `isFinite` `encodeURIComponent`
100
+ `decodeURIComponent`,以及 `log(...)`(内容会随结果回给调用方)。
101
+
102
+ **没有**:`require` / `process` / `fs` / `fetch` / `setTimeout` / `console`,
103
+ 也没有 `eval` 和 `new Function`。脚本必须是**同步**的——返回 Promise 会被判为错误。
104
+
105
+ 超过超时(默认 120ms)会被强制中断。
106
+
107
+ ## 关键约定
108
+
109
+ **脚本自己崩了,不等于校验不通过。** 抛异常 / 超时只会记一次告警并**放行**这次
110
+ 操作——否则一段写坏的校验器会让整个记忆系统无法写入,等于丢数据。所以:
111
+
112
+ - 想让保存失败,就**正常返回** `{ ok: false }`;
113
+ - 不要用 `throw` 表达"不合规"。
114
+
115
+ ## 上手流程
116
+
117
+ ```
118
+ 1. skill 工具加载本技能(你正在读)
119
+ 2. memory_hooks({ action: 'run', id: '<hook id>', content: '<试跑正文>' })
120
+ —— 先看脚本对一段样例的判断,别直接上线
121
+ 3. memory_save({ ..., hookCode: '...', hookPhase: 'before-save' })
122
+ —— 随规则一起登记;用户会看到代码并批准一次
123
+ 4. memory_hooks({ action: 'list' })
124
+ —— 确认 pendingApproval 不是 true(未批准 = 不会运行)
125
+ ```
126
+
127
+ 改代码之后要重新批准:审批记的是**代码指纹**,改一个字符就会重新变回待批准。
128
+
129
+ ## 常见错误
130
+
131
+ | 现象 | 原因 |
132
+ |---|---|
133
+ | `脚本里找不到入口函数` | 没定义 `verify` / `observe` / `parse` / `main` |
134
+ | `脚本无法加载` | 用了 `require` / `import` / 顶层 `await` |
135
+ | `脚本执行超时` | 死循环,或对超大字符串做了正则回溯 |
136
+ | 判定总是通过 | 忘了 `return`,函数隐式返回 `undefined`(= 通过) |
137
+ | 代码改了却不生效 | 还是待批准状态,跑一次 `action: 'approve'` |
138
+
139
+ ## 更多范例
140
+
141
+ `references/examples.md` 里有:长度/标签/类型规范、重复检测、注入前脱敏与摘要压缩、
142
+ 按作用域分支的校验。写新脚本前先看一眼,多数场景是改一改现成的。
@@ -0,0 +1,159 @@
1
+ # 现成范例
2
+
3
+ 这些都是能直接用的脚本。改的时候只动判断条件,别动返回值形状 —— 形状是
4
+ `memory-hook-scripts` 正文里的约定。
5
+
6
+ ## 1. 「概括:正文」格式(before-save)
7
+
8
+ 最常见的规则:这条记忆必须以一句能独立看懂的概括句开头,后面用全角冒号接正文。
9
+
10
+ ```js
11
+ function verify(memory) {
12
+ const text = memory.content
13
+ const at = text.indexOf(':')
14
+ if (at < 0) {
15
+ return { ok: false, message: '必须以「概括句:正文」格式保存:先写一句能独立看懂的概括,再用全角冒号「:」接正文' }
16
+ }
17
+ const head = text.slice(0, at).trim()
18
+ const body = text.slice(at + 1).trim()
19
+ if (head === '') return { ok: false, message: '冒号前是空的:概括句必须能独立看懂,不能省略' }
20
+ if (body === '') return { ok: false, message: '冒号后是空的:正文不能省略' }
21
+ if (head.length > 80) {
22
+ return { ok: false, message: '概括句 ' + head.length + ' 字,太长;压到 80 字以内,把细节挪到正文' }
23
+ }
24
+ return { ok: true }
25
+ }
26
+ ```
27
+
28
+ 注意用 `indexOf(':')` 而不是 `includes`:半角 `:` 不算,避免模型偷懒用英文冒号。
29
+
30
+ ## 2. 规则记忆必须能独立读懂(before-save,只拦 rule)
31
+
32
+ 模型很容易写出「同上」「按上次说的做」这种离开上下文就没用的规则。
33
+
34
+ ```js
35
+ function verify(memory, ctx) {
36
+ if (memory.kind !== 'rule') return true
37
+ const vague = ['同上', '如前所述', '按上次', '照旧', '同上条', '见上文']
38
+ const hit = vague.filter(function (word) { return memory.content.indexOf(word) >= 0 })
39
+ if (hit.length > 0) {
40
+ return { ok: false, message: '规则里出现了「' + hit.join('、') + '」这类离开上下文就看不懂的指代;把被指代的内容直接写出来' }
41
+ }
42
+ if (memory.content.trim().length < 12) {
43
+ return { ok: false, message: '规则太短(' + memory.content.trim().length + ' 字),很可能不完整;补上"什么时候做、具体做什么"' }
44
+ }
45
+ return { ok: true }
46
+ }
47
+ ```
48
+
49
+ ## 3. 必须带标签(before-save)
50
+
51
+ 按作用域约定标签,方便以后按标签检索。
52
+
53
+ ```js
54
+ function verify(memory) {
55
+ if (memory.scope !== 'dsh-plugin-dev') return true
56
+ const required = ['plugin']
57
+ const have = (memory.tags || []).map(function (t) { return String(t).toLowerCase() })
58
+ const missing = required.filter(function (tag) { return have.indexOf(tag) < 0 })
59
+ if (missing.length > 0) {
60
+ return { ok: false, message: '这个作用域的记录必须带标签 ' + missing.join('、') + ';请在 tags 里补上再保存' }
61
+ }
62
+ return { ok: true }
63
+ }
64
+ ```
65
+
66
+ ## 4. 凭证不入库(before-save)
67
+
68
+ 比 provider 自带的密钥扫描更早、更严格的一道闸。
69
+
70
+ ```js
71
+ function verify(memory) {
72
+ const text = memory.content
73
+ const patterns = [
74
+ /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
75
+ /\bsk-[A-Za-z0-9]{20,}\b/,
76
+ /\bgh[pousr]_[A-Za-z0-9]{20,}\b/,
77
+ /\bAKIA[0-9A-Z]{16}\b/,
78
+ /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\./
79
+ ]
80
+ for (let i = 0; i < patterns.length; i++) {
81
+ if (patterns[i].test(text)) {
82
+ return { ok: false, message: '正文里出现了疑似凭据(私钥 / API key / JWT)。凭据不要写进记忆:改成"用 devcred 里的 <名字>"这种指代' }
83
+ }
84
+ }
85
+ return { ok: true }
86
+ }
87
+ ```
88
+
89
+ ## 5. 注入前压缩长记录(before-inject)
90
+
91
+ 摘要预算有限,长记录会挤掉别人。把超长正文截断成首段 + 提示。
92
+
93
+ ```js
94
+ function parse(memory) {
95
+ const limit = 400
96
+ if (memory.content.length <= limit) return true
97
+ const cut = memory.content.slice(0, limit)
98
+ const at = Math.max(cut.lastIndexOf('。'), cut.lastIndexOf('\n'))
99
+ const head = at > limit * 0.5 ? cut.slice(0, at + 1) : cut
100
+ return {
101
+ content: head.trim() + ' …(原文 ' + memory.content.length + ' 字,需要全文用 memory_get ' + String(memory.id).slice(0, 8) + ')'
102
+ }
103
+ }
104
+ ```
105
+
106
+ ## 6. 注入前脱敏(before-inject)
107
+
108
+ 把 IP / 内网地址换成占位符,避免把环境细节喷进上下文。
109
+
110
+ ```js
111
+ function parse(memory) {
112
+ const cleaned = memory.content
113
+ .replace(/\b\d{1,3}(?:\.\d{1,3}){3}\b/g, '<IP>')
114
+ .replace(/\/Users\/[^\s,。;]+/g, '<PATH>')
115
+ .replace(/[A-Z]:\\[^\s,。;]+/g, '<PATH>')
116
+ if (cleaned === memory.content) return true
117
+ return { content: cleaned }
118
+ }
119
+ ```
120
+
121
+ ## 7. 注入前丢弃过期口吻(before-inject)
122
+
123
+ 「目前 / 现在」这类词在记忆里会随时间失真,干脆别注入。
124
+
125
+ ```js
126
+ function parse(memory) {
127
+ if (memory.kind !== 'state') return true
128
+ const age = Date.now() - Number(memory.updatedAt || 0)
129
+ const days = age / 86400000
130
+ if (days > 30) return { drop: true } // 30 天前的状态型记忆不再注入
131
+ return true
132
+ }
133
+ ```
134
+
135
+ ## 8. 保存后观察:把可疑内容记下来(after-save)
136
+
137
+ 观察者不能改结果,但能留下痕迹(`log()` 的内容会随结果回给调用方)。
138
+
139
+ ```js
140
+ function observe(memory) {
141
+ if (memory.content.length > 1500) {
142
+ log('超长记录', memory.id, memory.content.length + ' 字')
143
+ return { message: '这条记录偏长(' + memory.content.length + ' 字),考虑拆成两条便于检索' }
144
+ }
145
+ return true
146
+ }
147
+ ```
148
+
149
+ ## 调试脚本
150
+
151
+ 不要靠猜。用 `run` 拿几段样例跑一遍:
152
+
153
+ ```
154
+ memory_hooks({ action: 'run', id: '<id>', content: '这段没有冒号' })
155
+ memory_hooks({ action: 'run', id: '<id>', content: '记忆内容规范:这段合规' })
156
+ ```
157
+
158
+ `run` 只跑脚本、不写记忆,是验证判断边界最快的方式。注意 `run` 用的是脚本保存时
159
+ 记下的 `scopes` / `kinds` 的第一个值;要让脚本命中,样例的 `kind` 必须匹配。