dsh-soul 0.7.2 → 0.9.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/README.md +39 -2
- package/README_EN.md +39 -2
- package/client/index.mjs +3497 -99
- package/index.mjs +1966 -121
- package/lib/bindings.mjs +430 -0
- package/lib/config.mjs +82 -1
- package/lib/history.mjs +605 -0
- package/lib/personas.mjs +59 -0
- package/lib/session-scope.mjs +432 -0
- package/lib/workspace-scope.mjs +348 -0
- package/package.json +9 -4
- package/scripts/verify-bindings.mjs +552 -0
- package/scripts/verify-client.mjs +2209 -16
- package/scripts/verify-config.mjs +1929 -24
- package/scripts/verify-e2e-prompt.mjs +1186 -24
- package/scripts/verify-history.mjs +782 -0
- package/scripts/verify-scope.mjs +328 -0
- package/scripts/verify-session-scope.mjs +435 -0
|
@@ -0,0 +1,432 @@
|
|
|
1
|
+
// lib/session-scope.mjs — 会话级人设覆盖(纯函数层 + sidecar 读写)
|
|
2
|
+
//
|
|
3
|
+
// 职责:
|
|
4
|
+
// - 单个会话覆盖项的形状校验(读侧一律当不可信输入)
|
|
5
|
+
// - sidecar 路径推导(`sha256(sessionId)` 作文件名)
|
|
6
|
+
// - 三阶段回收的状态机(发现候选 → 宽限期 → 可回收)
|
|
7
|
+
//
|
|
8
|
+
// 五条设计前提,改本模块前请先读:
|
|
9
|
+
//
|
|
10
|
+
// 1. **会话覆盖是「状态」,不是「配置」。** 它随会话生灭、数量无上界、用户不在意它的
|
|
11
|
+
// 变更历史。所以放独立 sidecar(`$DSH_HOME/soul-sessions/`),不进 soul-config.json ——
|
|
12
|
+
// 塞进配置会让文件被短命的会话 id 无限撑大(0.8.0 刚为历史文件做过压实)。
|
|
13
|
+
// 2. **文件名必须哈希,不能直接拼接 sessionId。** 会话 id 的字符集由宿主决定,
|
|
14
|
+
// 没有证据表明它一定对文件系统安全。哈希定长、无歧义,且天然规避 `..` 之类的路径穿越。
|
|
15
|
+
// 文件**内容**里另存原始 sessionId,两者必须互相校验 —— 否则改个文件名就能让
|
|
16
|
+
// 某个会话读到另一个会话的覆盖。
|
|
17
|
+
// 3. **绝不用「agents.list() 里没有」判定会话已删除。** 那是 live registry,
|
|
18
|
+
// 会话切走、进程重启都会让它消失,但会话文件仍在磁盘上。用它判定会误删正在使用的
|
|
19
|
+
// 覆盖。唯一可信证据是 `sessionPersistence.list()`(扫磁盘)。
|
|
20
|
+
// 4. **缺证据时保留,不删除。** 清理是**单向下行**的操作:删错了用户永久丢失设置;
|
|
21
|
+
// 留着只是多几个小文件。所以凡是不确定的情况(服务不可用、扫描不完整、宽限期资料
|
|
22
|
+
// 缺失)一律不删。
|
|
23
|
+
// 5. **本模块不碰宿主 ctx。** 纯函数 + 文件读写,可被脚本独立加载测试(与
|
|
24
|
+
// lib/store.mjs、lib/history.mjs、lib/bindings.mjs 同一条约定)。
|
|
25
|
+
|
|
26
|
+
import { createHash } from 'node:crypto'
|
|
27
|
+
import { readdir, stat } from 'node:fs/promises'
|
|
28
|
+
import { dirname, join } from 'node:path'
|
|
29
|
+
import { moveAsideConfigFile, readConfigFile, writeConfigFile } from './store.mjs'
|
|
30
|
+
|
|
31
|
+
// ==================== 契约常量 ====================
|
|
32
|
+
|
|
33
|
+
// sidecar 格式版本。读到不认识的版本时**整条忽略**(并保留文件,见前提 4):
|
|
34
|
+
// 升级后的字段语义无法保证,按错的方式解析会给出一个看似正常、实则错误的人设。
|
|
35
|
+
export const SESSION_SCOPE_VERSION = 1
|
|
36
|
+
|
|
37
|
+
// 一个会话能覆盖的字段白名单。
|
|
38
|
+
//
|
|
39
|
+
// 与会话级覆盖的目的完全一致:**只改这一次对话的表现**。所以它与人设字段同集合,
|
|
40
|
+
// 但**刻意不含** `enabled`(全局总开关,见下)与 `historyMaxEntries`(全局设施)。
|
|
41
|
+
export const SESSION_OVERRIDE_FIELDS = Object.freeze([
|
|
42
|
+
'style',
|
|
43
|
+
'headingLists',
|
|
44
|
+
'emoji',
|
|
45
|
+
'tables',
|
|
46
|
+
'replyLength',
|
|
47
|
+
'language',
|
|
48
|
+
'customInstructions'
|
|
49
|
+
])
|
|
50
|
+
|
|
51
|
+
// 任何作用域都不能覆盖的字段。与 lib/workspace-scope.mjs 的 ENVELOPE_ONLY_FIELDS 同义
|
|
52
|
+
// (两处独立列举:它们服务不同的数据形状,共享常量会让一处改动悄悄影响另一处)。
|
|
53
|
+
export const SESSION_ENVELOPE_ONLY_FIELDS = Object.freeze(['enabled'])
|
|
54
|
+
|
|
55
|
+
// 会话覆盖的宽限期(毫秒)。30 天。
|
|
56
|
+
//
|
|
57
|
+
// 这个数字**不是**普适标准,而是一个保守默认:宿主是否支持归档、离线会话、历史恢复
|
|
58
|
+
// 都还没有定论(会话文件可能长期存在但不活跃)。宁可留着。
|
|
59
|
+
export const ORPHAN_GRACE_MS = 30 * 24 * 60 * 60 * 1000
|
|
60
|
+
|
|
61
|
+
// 文件名哈希取前多少位。32 个 hex 字符 = 128 bit,碰撞概率可忽略;
|
|
62
|
+
// 文件名长度也远在常见文件系统上限之内。
|
|
63
|
+
export const FILE_HASH_LENGTH = 32
|
|
64
|
+
|
|
65
|
+
// sidecar 顶层目录名(相对 `$DSH_HOME`)。
|
|
66
|
+
export const SESSION_DIR_NAME = 'soul-sessions'
|
|
67
|
+
|
|
68
|
+
// sessionId 的长度上限。宿主用 SessionId 品牌类型,实测形如 `session-<uuid>`;
|
|
69
|
+
// 给一个宽松上限只为拦住把整段路径塞进 id 这类错误用法。
|
|
70
|
+
export const MAX_SESSION_ID_LENGTH = 256
|
|
71
|
+
|
|
72
|
+
// 单条覆盖的字段数上限(白名单本身只有 7 个,这里防的是异常数据)。
|
|
73
|
+
export const MAX_SESSION_OVERRIDE_KEYS = 16
|
|
74
|
+
|
|
75
|
+
// ==================== 路径与键 ====================
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* 判断一个值能否当作 sessionId。
|
|
79
|
+
* @param {unknown} raw
|
|
80
|
+
* @returns {boolean}
|
|
81
|
+
*/
|
|
82
|
+
export function isSessionId(raw) {
|
|
83
|
+
if (typeof raw !== 'string') return false
|
|
84
|
+
const id = raw.trim()
|
|
85
|
+
if (id === '') return false
|
|
86
|
+
if (id.length > MAX_SESSION_ID_LENGTH) return false
|
|
87
|
+
// 路径分隔符在入口就拒绝:sessionId 不该长成路径,而放行它等于把路径穿越的口子
|
|
88
|
+
// 留给下游(虽然文件名是哈希,但内容里的 sessionId 会被展示与比较)。
|
|
89
|
+
if (id.includes('\\') || id.includes('/')) return false
|
|
90
|
+
if (id === '.' || id === '..') return false
|
|
91
|
+
return true
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* 由 sessionId 算出 sidecar 文件名(不含目录)。
|
|
96
|
+
*
|
|
97
|
+
* 用 sha256 而不是转义:转义规则要跟随不同文件系统,哈希定长且无歧义。
|
|
98
|
+
* @param {string} sessionId
|
|
99
|
+
* @returns {string}
|
|
100
|
+
*/
|
|
101
|
+
export function sessionFileName(sessionId) {
|
|
102
|
+
const digest = createHash('sha256').update(String(sessionId), 'utf8').digest('hex')
|
|
103
|
+
return `${digest.slice(0, FILE_HASH_LENGTH)}.json`
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/**
|
|
107
|
+
* sidecar 目录路径:与 `soul-config.json` **同级**。
|
|
108
|
+
*
|
|
109
|
+
* 由配置文件路径推导而不是自己拼 `$DSH_HOME`:这样测试把配置指到临时目录时,
|
|
110
|
+
* sidecar 自动跟着走(与 `bindingsPathFor` 同一条约定)。
|
|
111
|
+
*
|
|
112
|
+
* @param {string} configFilePath
|
|
113
|
+
* @returns {string}
|
|
114
|
+
*/
|
|
115
|
+
export function sessionScopeDirFor(configFilePath) {
|
|
116
|
+
return join(dirname(configFilePath), SESSION_DIR_NAME)
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* 单个会话的 sidecar 完整路径。
|
|
121
|
+
* @param {string} configFilePath
|
|
122
|
+
* @param {string} sessionId
|
|
123
|
+
* @returns {string}
|
|
124
|
+
*/
|
|
125
|
+
export function sessionScopePathFor(configFilePath, sessionId) {
|
|
126
|
+
return join(sessionScopeDirFor(configFilePath), sessionFileName(sessionId))
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
// ==================== 校验 ====================
|
|
130
|
+
|
|
131
|
+
function isEmptyObject(value) {
|
|
132
|
+
return !!value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* 校验一份覆盖项。
|
|
137
|
+
*
|
|
138
|
+
* @param {unknown} raw
|
|
139
|
+
* @returns {{ override: Record<string, unknown> | null, dropped: string[] }}
|
|
140
|
+
*/
|
|
141
|
+
export function sanitizeSessionOverride(raw) {
|
|
142
|
+
const dropped = []
|
|
143
|
+
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
|
|
144
|
+
return { override: null, dropped }
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
const override = {}
|
|
148
|
+
for (const [key, value] of Object.entries(raw)) {
|
|
149
|
+
if (SESSION_ENVELOPE_ONLY_FIELDS.includes(key)) { dropped.push(key); continue }
|
|
150
|
+
if (!SESSION_OVERRIDE_FIELDS.includes(key)) { dropped.push(key); continue }
|
|
151
|
+
override[key] = value
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
if (Object.keys(override).length > MAX_SESSION_OVERRIDE_KEYS) {
|
|
155
|
+
// 超限说明数据被污染了(白名单只有 7 个键),整条丢弃比挑着留更安全。
|
|
156
|
+
return { override: null, dropped: dropped.concat(Object.keys(override)) }
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
return { override: isEmptyObject(override) ? null : override, dropped }
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* 构造一份新的 sidecar 文档。
|
|
164
|
+
*
|
|
165
|
+
* @param {string} sessionId
|
|
166
|
+
* @param {object} override 已校验的覆盖项
|
|
167
|
+
* @param {number} [now] 可注入的时钟(测试用)
|
|
168
|
+
* @param {string} [personaName] 用户实际选中的预设名(见下方说明)
|
|
169
|
+
* @returns {object}
|
|
170
|
+
*/
|
|
171
|
+
export function createSessionScopeDoc(sessionId, override, now = Date.now(), personaName = null) {
|
|
172
|
+
const iso = new Date(now).toISOString()
|
|
173
|
+
const doc = {
|
|
174
|
+
schemaVersion: SESSION_SCOPE_VERSION,
|
|
175
|
+
sessionId,
|
|
176
|
+
overrides: { ...override },
|
|
177
|
+
createdAt: iso,
|
|
178
|
+
updatedAt: iso
|
|
179
|
+
}
|
|
180
|
+
// personaName:**用户实际选了哪个预设**。
|
|
181
|
+
//
|
|
182
|
+
// 为什么必须单独记:覆盖项本身只存字段(style/headingLists/…),不记预设名。
|
|
183
|
+
// 而「当前生效的是哪个预设」原先是**靠字段反查**出来的(findActivePersonaName:
|
|
184
|
+
// 拿当前配置去比每个预设,谁匹配上就是它,多个匹配时按名称排序取首个)。
|
|
185
|
+
// 这个反查在「两个预设声明了相同字段」时不确定:实测用户自建「游戏策划与开发专家」
|
|
186
|
+
// 与内置「自驱型协作者」字段一致时,名称排序让自建的那个抢先命中 ——
|
|
187
|
+
// 用户明明点了「自驱型协作者」,界面却显示「游戏策划与开发专家」。
|
|
188
|
+
//
|
|
189
|
+
// 记下名字就把「猜」变成了「知道」。字段仍照旧存(模型只认字段,
|
|
190
|
+
// 名字只是给人看的注解),两者并存不冲突。
|
|
191
|
+
if (typeof personaName === 'string' && personaName !== '') {
|
|
192
|
+
doc.personaName = personaName
|
|
193
|
+
}
|
|
194
|
+
return doc
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* 解析 sidecar 文档(读侧一律当不可信输入)。
|
|
199
|
+
*
|
|
200
|
+
* 三种失败都必须**区分开**,因为调用方的处理不同:
|
|
201
|
+
* - 形状/版本不对 → 忽略内容,但**保留文件**(可能是更新的版本写的)
|
|
202
|
+
* - sessionId 与文件名不符 → 忽略内容,保留文件(防错配)
|
|
203
|
+
* - 覆盖项为空 → 视为"没有覆盖",可安全删除
|
|
204
|
+
*
|
|
205
|
+
* @param {unknown} raw
|
|
206
|
+
* @param {string} expectedSessionId 文件名推导出的期望 id
|
|
207
|
+
* @returns {{ override: object | null, failure: string | null, orphan: object | null, doc: object | null }}
|
|
208
|
+
*/
|
|
209
|
+
export function parseSessionScopeDoc(raw, expectedSessionId) {
|
|
210
|
+
const empty = { override: null, failure: null, orphan: null, doc: null }
|
|
211
|
+
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
|
|
212
|
+
return { ...empty, failure: 'sidecar 不是 JSON 对象' }
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
const version = raw.schemaVersion
|
|
216
|
+
if (version !== SESSION_SCOPE_VERSION) {
|
|
217
|
+
return { ...empty, failure: `sidecar 版本 ${String(version)} 不认识(当前支持 ${SESSION_SCOPE_VERSION})` }
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
// sessionId 必须与文件内容一致:改个文件名就能让某个会话读到另一个会话的覆盖。
|
|
221
|
+
if (typeof raw.sessionId !== 'string' || raw.sessionId !== expectedSessionId) {
|
|
222
|
+
return { ...empty, failure: `sidecar 内的 sessionId 与文件名不符(文件里是 ${String(raw.sessionId)})` }
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
const { override } = sanitizeSessionOverride(raw.overrides)
|
|
226
|
+
const orphan = parseOrphanState(raw.orphan)
|
|
227
|
+
|
|
228
|
+
// personaName:用户实际选的预设名。缺失(老版本 sidecar)或不是字符串都当作没有 ——
|
|
229
|
+
// 调用方会退回「按字段反查」,那是不确定但可用的旧路径。
|
|
230
|
+
const personaName = typeof raw.personaName === 'string' && raw.personaName !== ''
|
|
231
|
+
? raw.personaName
|
|
232
|
+
: null
|
|
233
|
+
|
|
234
|
+
return {
|
|
235
|
+
override,
|
|
236
|
+
failure: null,
|
|
237
|
+
orphan,
|
|
238
|
+
personaName,
|
|
239
|
+
doc: {
|
|
240
|
+
schemaVersion: SESSION_SCOPE_VERSION,
|
|
241
|
+
sessionId: expectedSessionId,
|
|
242
|
+
overrides: override,
|
|
243
|
+
personaName,
|
|
244
|
+
createdAt: typeof raw.createdAt === 'string' ? raw.createdAt : null,
|
|
245
|
+
updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt : null
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
/**
|
|
251
|
+
* 解析孤儿标记。缺失即「从未被标记」。
|
|
252
|
+
* @param {unknown} raw
|
|
253
|
+
* @returns {{ firstSeenAt: string, lastScannedAt: string } | null}
|
|
254
|
+
*/
|
|
255
|
+
function parseOrphanState(raw) {
|
|
256
|
+
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
|
|
257
|
+
const firstSeenAt = typeof raw.firstSeenAt === 'string' ? raw.firstSeenAt : null
|
|
258
|
+
if (firstSeenAt === null) return null
|
|
259
|
+
// firstSeenAt 必须是可解析的时间:解析不了等于没有资料,按「未标记」处理更安全
|
|
260
|
+
if (!Number.isFinite(Date.parse(firstSeenAt))) return null
|
|
261
|
+
return {
|
|
262
|
+
firstSeenAt,
|
|
263
|
+
lastScannedAt: typeof raw.lastScannedAt === 'string' ? raw.lastScannedAt : firstSeenAt
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
// ==================== 回收状态机 ====================
|
|
268
|
+
|
|
269
|
+
/**
|
|
270
|
+
* 判定一个 sidecar 在**本轮扫描**下的状态。
|
|
271
|
+
*
|
|
272
|
+
* 这是整个回收逻辑的核心,纯函数、可穷举测试。三阶段对应设计 §5.2:
|
|
273
|
+
*
|
|
274
|
+
* 阶段 1「发现候选」:本轮扫描成功且该 id 不在磁盘会话清单里 → 写入 orphan.firstSeenAt
|
|
275
|
+
* 阶段 2「宽限期」 :已有 orphan 但未满 30 天 → 不删;若该 id 重新出现 → 撤销标记
|
|
276
|
+
* 阶段 3「可回收」 :已有 orphan、满 30 天、且本轮扫描**完整成功** → 才允许删
|
|
277
|
+
*
|
|
278
|
+
* 「本轮扫描成功」是**独立的一票否决**:如果持久化层不可用,30 天只度量了
|
|
279
|
+
* 「我们多久没检查」,不能拿来当删除依据。
|
|
280
|
+
*
|
|
281
|
+
* @param {object} input
|
|
282
|
+
* @param {{ firstSeenAt: string } | null} input.orphan 现有标记
|
|
283
|
+
* @param {boolean} input.presentOnDisk 该会话是否在本轮磁盘清单里
|
|
284
|
+
* @param {boolean} input.scanComplete 本轮扫描是否完整成功
|
|
285
|
+
* @param {number} [input.now]
|
|
286
|
+
* @param {number} [input.graceMs]
|
|
287
|
+
* @returns {{ action: 'keep' | 'mark' | 'clear-mark' | 'collect', orphan: object | null, reason: string }}
|
|
288
|
+
*/
|
|
289
|
+
export function decideSessionScopeFate(input) {
|
|
290
|
+
const now = Number.isFinite(input.now) ? input.now : Date.now()
|
|
291
|
+
const graceMs = Number.isFinite(input.graceMs) ? input.graceMs : ORPHAN_GRACE_MS
|
|
292
|
+
const current = input.orphan || null
|
|
293
|
+
|
|
294
|
+
// 会话还在磁盘上 —— 无论之前有没有标记,都要撤销候选状态。
|
|
295
|
+
if (input.presentOnDisk) {
|
|
296
|
+
if (current !== null) {
|
|
297
|
+
return { action: 'clear-mark', orphan: null, reason: '会话重新出现,撤销孤儿标记' }
|
|
298
|
+
}
|
|
299
|
+
return { action: 'keep', orphan: null, reason: '会话存在' }
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
// 会话不在清单里,但本轮扫描不完整 —— **不标记、不删除**。
|
|
303
|
+
// 这一步是「缺证据时保留」的直接落地:扫描不完整意味着"没看到"不等于"不存在"。
|
|
304
|
+
if (!input.scanComplete) {
|
|
305
|
+
return { action: 'keep', orphan: current, reason: '本轮扫描不完整,不做任何判定' }
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
// 第一次发现缺席:标记候选,不删除。
|
|
309
|
+
if (current === null) {
|
|
310
|
+
return {
|
|
311
|
+
action: 'mark',
|
|
312
|
+
orphan: { firstSeenAt: new Date(now).toISOString(), lastScannedAt: new Date(now).toISOString() },
|
|
313
|
+
reason: '首次发现会话缺席,标记为候选'
|
|
314
|
+
}
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
const firstSeen = Date.parse(current.firstSeenAt)
|
|
318
|
+
if (!Number.isFinite(firstSeen)) {
|
|
319
|
+
// 标记里的时间坏了:当作"刚发现",重新计时(宁可多留 30 天)
|
|
320
|
+
return {
|
|
321
|
+
action: 'mark',
|
|
322
|
+
orphan: { firstSeenAt: new Date(now).toISOString(), lastScannedAt: new Date(now).toISOString() },
|
|
323
|
+
reason: '孤儿标记的时间不可解析,重新计时'
|
|
324
|
+
}
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
const age = now - firstSeen
|
|
328
|
+
if (age < graceMs) {
|
|
329
|
+
return {
|
|
330
|
+
action: 'keep',
|
|
331
|
+
orphan: { firstSeenAt: current.firstSeenAt, lastScannedAt: new Date(now).toISOString() },
|
|
332
|
+
reason: `宽限期内(剩余 ${Math.ceil((graceMs - age) / (24 * 3600 * 1000))} 天)`
|
|
333
|
+
}
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
return {
|
|
337
|
+
action: 'collect',
|
|
338
|
+
orphan: current,
|
|
339
|
+
reason: `缺席已超过 ${Math.round(graceMs / (24 * 3600 * 1000))} 天,且本轮扫描完整`
|
|
340
|
+
}
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
// ==================== 文件读写 ====================
|
|
344
|
+
|
|
345
|
+
/**
|
|
346
|
+
* 读一个会话的 sidecar。
|
|
347
|
+
*
|
|
348
|
+
* 与 lib/store.mjs 的 `readConfigFile` 同一套语义(不存在 / 可读 / 损坏三分),
|
|
349
|
+
* 但**不做自动备份**:sidecar 是"状态",损坏时忽略即可,不需要惊动用户。
|
|
350
|
+
* 真正的隔离(改名 `.bad`)由 GC 命令显式执行 —— 那是一个可审计的动作。
|
|
351
|
+
*
|
|
352
|
+
* @param {string} filePath
|
|
353
|
+
* @param {string} expectedSessionId
|
|
354
|
+
* @returns {Promise<{ override: object | null, failure: string | null, orphan: object | null, doc: object | null, exists: boolean }>}
|
|
355
|
+
*/
|
|
356
|
+
export async function readSessionScope(filePath, expectedSessionId) {
|
|
357
|
+
const { value, exists, failure } = await readConfigFile(filePath)
|
|
358
|
+
if (!exists) return { override: null, failure: null, orphan: null, doc: null, exists: false }
|
|
359
|
+
if (failure) {
|
|
360
|
+
return { override: null, failure: `读取失败:${failure.message}`, orphan: null, doc: null, exists: true }
|
|
361
|
+
}
|
|
362
|
+
const parsed = parseSessionScopeDoc(value, expectedSessionId)
|
|
363
|
+
return { ...parsed, exists: true }
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
/**
|
|
367
|
+
* 写一个会话的 sidecar(原子替换)。
|
|
368
|
+
* @param {string} filePath
|
|
369
|
+
* @param {object} doc
|
|
370
|
+
* @returns {Promise<void>}
|
|
371
|
+
*/
|
|
372
|
+
export async function writeSessionScope(filePath, doc) {
|
|
373
|
+
await writeConfigFile(filePath, doc)
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
/**
|
|
377
|
+
* 把损坏 / 不可用的 sidecar 移开(`.bad` 后缀)。
|
|
378
|
+
*
|
|
379
|
+
* 只在**显式清理**时调用,绝不在读取路径上自动执行:读取是每轮都可能发生的,
|
|
380
|
+
* 让它产生副作用会让"看一眼会话"变成"改了磁盘"。
|
|
381
|
+
*
|
|
382
|
+
* @param {string} filePath
|
|
383
|
+
* @returns {Promise<string | null>} 移开后的路径;移不动返回 null
|
|
384
|
+
*/
|
|
385
|
+
export async function quarantineSessionScope(filePath) {
|
|
386
|
+
return await moveAsideConfigFile(filePath)
|
|
387
|
+
}
|
|
388
|
+
|
|
389
|
+
/**
|
|
390
|
+
* 列出 sidecar 目录里的全部候选文件(不读内容)。
|
|
391
|
+
*
|
|
392
|
+
* 目录不存在时返回空数组而不抛错:首次使用就是"没有覆盖"。
|
|
393
|
+
* @param {string} dir
|
|
394
|
+
* @returns {Promise<Array<{ name: string, path: string, size: number, mtimeMs: number }>>}
|
|
395
|
+
*/
|
|
396
|
+
export async function listSessionScopes(dir) {
|
|
397
|
+
let names
|
|
398
|
+
try {
|
|
399
|
+
names = await readdir(dir)
|
|
400
|
+
} catch (err) {
|
|
401
|
+
if (err && err.code === 'ENOENT') return []
|
|
402
|
+
throw err
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
const out = []
|
|
406
|
+
for (const name of names) {
|
|
407
|
+
if (!name.endsWith('.json')) continue
|
|
408
|
+
const path = join(dir, name)
|
|
409
|
+
try {
|
|
410
|
+
const info = await stat(path)
|
|
411
|
+
if (!info.isFile()) continue
|
|
412
|
+
out.push({ name, path, size: info.size, mtimeMs: info.mtimeMs })
|
|
413
|
+
} catch {
|
|
414
|
+
// 单个文件 stat 失败(被并发删除 / 权限):跳过,不让整次扫描失败
|
|
415
|
+
continue
|
|
416
|
+
}
|
|
417
|
+
}
|
|
418
|
+
return out
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
/**
|
|
422
|
+
* 由文件名反查 sessionId。
|
|
423
|
+
*
|
|
424
|
+
* 哈希是**单向**的,所以无法从文件名还原 id。调用方必须读文件内容拿 id,
|
|
425
|
+
* 并校验内容与文件名是否互相对应(见 parseSessionScopeDoc)。
|
|
426
|
+
*
|
|
427
|
+
* 这个函数存在只是为了把"为什么不能反查"写进代码(避免将来有人试图用文件名当键)。
|
|
428
|
+
* @returns {null}
|
|
429
|
+
*/
|
|
430
|
+
export function sessionIdFromFileName() {
|
|
431
|
+
return null
|
|
432
|
+
}
|