@restregular/dsh-memory 0.31.0 → 0.33.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,279 @@
1
+ /**
2
+ * 「屏蔽」持久化(0.32.0)。
3
+ *
4
+ * Agent 可以主动把**与当前任务无关**的记忆屏蔽掉,让它们不再进入检索、注入与
5
+ * 目录统计。屏蔽与「归档」「可见域」是三件不同的事:
6
+ *
7
+ * - 归档(0.30.0)是**宿主生命周期**事实:会话被归档 / 工作区被移除,记忆冻结,
8
+ * 恢复后自动复原,没有审批路径;
9
+ * - 可见域(0.19.0+)是**用户**设定的读写边界:范围外要靠审批放行;
10
+ * - 屏蔽是本条记录/这个作用域**被主动藏起来**:不删数据、不改可见域,
11
+ * 解除屏蔽即刻复原。
12
+ *
13
+ * 两个层级(用户口径):
14
+ * - `session` —— 只影响当前会话(含沿 parentSession 链继承的子 Agent),**不需要审批**;
15
+ * - `workspace` —— 影响该工作区里**所有会话**(含历史与将来),**必须审批**。
16
+ *
17
+ * 文件位置:
18
+ * - 会话级:`<root>/blocks/session/<safeName(sessionId)>.json`
19
+ * - 工作区级:`<root>/blocks/workspace/<sha1(workspaceKey)>.json`
20
+ *
21
+ * 为什么按会话 / 工作区分文件:storeDir 可能被多个进程共用(见 store.ts 的 issue #3),
22
+ * 单文件 map 在并发写时会互相覆盖;分文件后一次写只碰自己那份。
23
+ *
24
+ * 容错:读写失败只退化为「没有屏蔽」,绝不把异常抛回检索 / 注入 / 面板链路。
25
+ */
26
+ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
27
+ import { createHash, randomUUID } from 'node:crypto'
28
+ import { join } from 'node:path'
29
+
30
+ export const BLOCKS_VERSION = 1
31
+
32
+ /** 屏蔽的作用层级。 */
33
+
34
+
35
+ /**
36
+ * 一条屏蔽。`scope` 与 `recordId` 二选一(都给了就都生效):
37
+ * - `scope` —— 整个作用域被屏蔽;
38
+ * - `recordId` —— 单条记忆(`prefix` 是模型给的前缀,用于兼容 8 位短 id)。
39
+ */
40
+
41
+
42
+
43
+
44
+                      
45
+
46
+               
47
+
48
+                               
49
+
50
+
51
+
52
+
53
+
54
+
55
+
56
+
57
+
58
+
59
+
60
+
61
+
62
+ /**
63
+ * `add` 的入参:`id` / `createdAt` / `createdBy` 可省略,由 store 补齐。
64
+ * 这样调用方不用自己拼 id 与时间戳,也不会写出半条记录。
65
+ */
66
+
67
+
68
+
69
+
70
+
71
+
72
+
73
+
74
+
75
+
76
+
77
+ const MAX_BLOCKS_PER_FILE = 500
78
+
79
+ function safeSessionName(sessionId ) {
80
+ const cleaned = sessionId.replace(/[^A-Za-z0-9._-]+/g, '_').slice(0, 80)
81
+ if (cleaned === sessionId && cleaned !== '') return cleaned
82
+ const base = cleaned === '' ? 'session' : cleaned.slice(0, 64)
83
+ return `${base}-${createHash('sha1').update(sessionId).digest('hex').slice(0, 8)}`
84
+ }
85
+
86
+ function workspaceFileName(workspace ) {
87
+ return `${createHash('sha1').update(workspace).digest('hex').slice(0, 20)}.json`
88
+ }
89
+
90
+ function cleanText(raw , max ) {
91
+ if (typeof raw !== 'string') return undefined
92
+ const value = raw.replace(/\s+/g, ' ').trim()
93
+ return value === '' ? undefined : value.slice(0, max)
94
+ }
95
+
96
+ /** 解析一条屏蔽;形状不对就丢掉(宁可少一条屏蔽,也不要拿坏数据去过滤)。 */
97
+ function parseBlock(raw , level ) {
98
+ if (raw === null || typeof raw !== 'object') return undefined
99
+ const item = raw
100
+ const scope = cleanText(item.scope, 512)
101
+ const recordId = cleanText(item.recordId, 128)
102
+ const prefix = cleanText(item.prefix, 128)
103
+ if (scope === undefined && recordId === undefined && prefix === undefined) return undefined
104
+ const id = cleanText(item.id, 128) ?? randomUUID()
105
+ const createdAt = typeof item.createdAt === 'number' && Number.isFinite(item.createdAt) ? item.createdAt : 0
106
+ return {
107
+ id,
108
+ level,
109
+ ...(scope !== undefined ? { scope } : {}),
110
+ ...(recordId !== undefined ? { recordId } : {}),
111
+ ...(prefix !== undefined ? { prefix } : {}),
112
+ ...(cleanText(item.recordKind, 64) !== undefined ? { recordKind: cleanText(item.recordKind, 64) } : {}),
113
+ createdAt,
114
+ createdBy: cleanText(item.createdBy, 128) ?? 'agent',
115
+ ...(cleanText(item.reason, 500) !== undefined ? { reason: cleanText(item.reason, 500) } : {}),
116
+ }
117
+ }
118
+
119
+ function cleanBlocks(raw , level ) {
120
+ if (!Array.isArray(raw)) return []
121
+ const out = []
122
+ const seen = new Set ()
123
+ for (const item of raw) {
124
+ const block = parseBlock(item, level)
125
+ if (block === undefined) continue
126
+ const key = block.scope !== undefined
127
+ ? `scope:${block.scope}`
128
+ : `record:${block.recordId ?? block.prefix ?? ''}`
129
+ if (seen.has(key)) continue
130
+ seen.add(key)
131
+ out.push(block)
132
+ if (out.length >= MAX_BLOCKS_PER_FILE) break
133
+ }
134
+ return out
135
+ }
136
+
137
+
138
+                
139
+
140
+
141
+
142
+
143
+ /**
144
+ * 会话级 + 工作区级屏蔽的读写。两个层级共用一套解析 / 原子写,只是文件目录不同。
145
+ */
146
+ export class MemoryBlocksStore {
147
+ dir
148
+ warn
149
+ /** `session:<id>` / `workspace:<key>` → 屏蔽列表;undefined = 还没读过。 */
150
+ cache = new Map ()
151
+
152
+ constructor(options ) {
153
+ this.dir = join(options.root, 'blocks')
154
+ this.warn = options.warn ?? ((message) => console.warn(message))
155
+ }
156
+
157
+ fileOf(level , key ) {
158
+ return level === 'session'
159
+ ? join(this.dir, 'session', `${safeSessionName(key)}.json`)
160
+ : join(this.dir, 'workspace', workspaceFileName(key))
161
+ }
162
+
163
+ cacheKey(level , key ) {
164
+ return `${level}:${key}`
165
+ }
166
+
167
+ /** 读一份屏蔽列表(拷贝)。key 对 session 是会话 id,对 workspace 是 `project:<路径>`。 */
168
+ list(level , key ) {
169
+ if (typeof key !== 'string' || key.trim() === '') return []
170
+ const trimmed = key.trim()
171
+ const cacheKey = this.cacheKey(level, trimmed)
172
+ const cached = this.cache.get(cacheKey)
173
+ if (cached !== undefined) return cached.map((block) => ({ ...block }))
174
+ let blocks = []
175
+ try {
176
+ const file = this.fileOf(level, trimmed)
177
+ if (existsSync(file)) {
178
+ const parsed = JSON.parse(readFileSync(file, 'utf8'))
179
+ // 文件里记录的 key 必须与查询一致:hash 碰撞时宁可当没有,也不串会话 / 工作区。
180
+ if (typeof parsed?.key === 'string' && parsed.key === trimmed) {
181
+ blocks = cleanBlocks(parsed.blocks, level)
182
+ }
183
+ }
184
+ } catch (error) {
185
+ this.warn(`[dsh-memory-local] 忽略损坏的屏蔽文件 ${this.fileOf(level, trimmed)}: ${error instanceof Error ? error.message : String(error)}`)
186
+ blocks = []
187
+ }
188
+ this.cache.set(cacheKey, blocks)
189
+ return blocks.map((block) => ({ ...block }))
190
+ }
191
+
192
+ /** 追加一条屏蔽(同目标已存在时替换)。返回写入后的完整列表。 */
193
+ add(level , key , block ) {
194
+ const current = this.list(level, key)
195
+ const full = {
196
+ id: block.id ?? `blk-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`,
197
+ level,
198
+ ...(block.scope !== undefined ? { scope: block.scope } : {}),
199
+ ...(block.recordId !== undefined ? { recordId: block.recordId } : {}),
200
+ ...(block.prefix !== undefined ? { prefix: block.prefix } : {}),
201
+ ...(block.recordKind !== undefined ? { recordKind: block.recordKind } : {}),
202
+ createdAt: block.createdAt ?? Date.now(),
203
+ createdBy: block.createdBy ?? 'agent',
204
+ ...(block.reason !== undefined ? { reason: block.reason } : {}),
205
+ }
206
+ const rest = current.filter((item) => !sameTarget(item, full))
207
+ return this.write(level, key, [...rest, full])
208
+ }
209
+
210
+ /** 按屏蔽 id 或目标移除;返回写入后的列表。 */
211
+ remove(level , key , match ) {
212
+ const current = this.list(level, key)
213
+ const rest = current.filter((item) => {
214
+ if (match.id !== undefined && item.id === match.id) return false
215
+ if (match.scope !== undefined && item.scope === match.scope) return false
216
+ const target = match.recordId ?? match.prefix
217
+ if (target !== undefined && (item.recordId === target || item.prefix === target)) return false
218
+ return true
219
+ })
220
+ return this.write(level, key, rest)
221
+ }
222
+
223
+ /** 清空某一层级的全部屏蔽。 */
224
+ clear(level , key ) {
225
+ return this.write(level, key, [])
226
+ }
227
+
228
+ /** 清掉缓存(下一次 list 重新读盘);测试 / 维护用。 */
229
+ invalidate(level , key ) {
230
+ this.cache.delete(this.cacheKey(level, key.trim()))
231
+ }
232
+
233
+ write(level , key , blocks ) {
234
+ const trimmed = typeof key === 'string' ? key.trim() : ''
235
+ if (trimmed === '') return []
236
+ const cleaned = blocks.slice(0, MAX_BLOCKS_PER_FILE)
237
+ const file = this.fileOf(level, trimmed)
238
+ try {
239
+ if (cleaned.length === 0) {
240
+ rmSync(file, { force: true })
241
+ this.cache.set(this.cacheKey(level, trimmed), [])
242
+ return []
243
+ }
244
+ mkdirSync(join(this.dir, level === 'session' ? 'session' : 'workspace'), { recursive: true })
245
+ const tmp = `${file}.${process.pid}.${Date.now()}.tmp`
246
+ writeFileSync(tmp, `${JSON.stringify({
247
+ version: BLOCKS_VERSION,
248
+ key: trimmed,
249
+ level,
250
+ blocks: cleaned,
251
+ updatedAt: Date.now(),
252
+ }, null, 2)}\n`, 'utf8')
253
+ renameSync(tmp, file)
254
+ this.cache.set(this.cacheKey(level, trimmed), cleaned)
255
+ return cleaned.map((block) => ({ ...block }))
256
+ } catch (error) {
257
+ this.warn(`[dsh-memory-local] 无法写入屏蔽文件 ${file}: ${error instanceof Error ? error.message : String(error)}`)
258
+ return this.list(level, trimmed)
259
+ }
260
+ }
261
+ }
262
+
263
+ /** 两条屏蔽是否指向同一个目标(scope 或同一条记录)。 */
264
+ function sameTarget(a , b ) {
265
+ if (a.scope !== undefined && b.scope !== undefined) return a.scope === b.scope
266
+ if (a.scope !== undefined || b.scope !== undefined) return false
267
+ return (a.recordId ?? a.prefix) === (b.recordId ?? b.prefix)
268
+ }
269
+
270
+ /** 一条记录是否命中某条屏蔽。 */
271
+ export function blockMatchesRecord(block , record ) {
272
+ if (block.scope !== undefined) return block.scope === record.scope
273
+ if (block.recordId !== undefined && block.recordId === record.id) return true
274
+ if (block.prefix !== undefined && record.id.startsWith(block.prefix)) return true
275
+ return false
276
+ }
277
+
278
+
279
+ //# sourceURL=source/memory-local/src/blocks.ts