dsh-retrace 0.4.151 → 0.4.152
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 +4 -4
- package/README.zh.md +4 -4
- package/lib/checkpoint-restore.js +42 -3
- package/lib/index.js +24 -1
- package/lib/preimage-store.js +30 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -35,7 +35,7 @@ it cannot dirty the log, and new markers create **no token-meter pairing debt**
|
|
|
35
35
|
|
|
36
36
|
> Versions: [VERSIONS.md](./VERSIONS.md)
|
|
37
37
|
|
|
38
|
-
> **0.4.
|
|
38
|
+
> **0.4.152 is the current release** — install/pin `0.4.152` (the **GitHub Release is out; the npm package is still pending** — the latest npm version is `0.4.139`; see [VERSIONS.md](./VERSIONS.md)). The `dsh-retrace@0.4.152` examples below apply to this release.
|
|
39
39
|
|
|
40
40
|
## ⚡ One-minute install
|
|
41
41
|
|
|
@@ -153,7 +153,7 @@ The same result with plain file edits and `pnpm` — exactly the steps
|
|
|
153
153
|
```json
|
|
154
154
|
{
|
|
155
155
|
"dependencies": {
|
|
156
|
-
"dsh-retrace": "^0.4.
|
|
156
|
+
"dsh-retrace": "^0.4.152"
|
|
157
157
|
},
|
|
158
158
|
"dsh": {
|
|
159
159
|
"profile": {
|
|
@@ -354,7 +354,7 @@ Historical details and exact error strings live in [CHANGELOG.md](./CHANGELOG.md
|
|
|
354
354
|
### Upgrading
|
|
355
355
|
|
|
356
356
|
```bash
|
|
357
|
-
dsh plugin --profile desktop add dsh-retrace@0.4.
|
|
357
|
+
dsh plugin --profile desktop add dsh-retrace@0.4.152
|
|
358
358
|
# then restart DSH — plugins are not hot-reloaded
|
|
359
359
|
```
|
|
360
360
|
|
|
@@ -378,7 +378,7 @@ whole tree down, so recover first and diagnose second:
|
|
|
378
378
|
|
|
379
379
|
### Pinning
|
|
380
380
|
|
|
381
|
-
Pin an exact plugin version (`dsh-retrace@0.4.
|
|
381
|
+
Pin an exact plugin version (`dsh-retrace@0.4.152`) and let `dsh-log-contract` resolve to
|
|
382
382
|
`>=0.3.18`. Do not rely on `^0.4` across a host upgrade: compatibility here is decided by
|
|
383
383
|
the **host surface**, not by semver alone.
|
|
384
384
|
|
package/README.zh.md
CHANGED
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
|
|
31
31
|
> 版本索引:[VERSIONS.md](./VERSIONS.md)
|
|
32
32
|
|
|
33
|
-
> **0.4.
|
|
33
|
+
> **0.4.152 为当前版本**——安装/固定请用 `0.4.152`(**GitHub Release 已发,npm 待发**;npm 最新可安装版本仍为 `0.4.139`,见 [VERSIONS.md](./VERSIONS.md));下文的 `dsh-retrace@0.4.152` 示例适用于该版本。
|
|
34
34
|
|
|
35
35
|
## ⚡ 一分钟安装
|
|
36
36
|
|
|
@@ -137,7 +137,7 @@ dsh plugin --profile <name> add dsh-retrace
|
|
|
137
137
|
```json
|
|
138
138
|
{
|
|
139
139
|
"dependencies": {
|
|
140
|
-
"dsh-retrace": "^0.4.
|
|
140
|
+
"dsh-retrace": "^0.4.152"
|
|
141
141
|
},
|
|
142
142
|
"dsh": {
|
|
143
143
|
"profile": {
|
|
@@ -315,7 +315,7 @@ Client 半区会依据包内 `dsh.client` 元数据被自动打包进 Web 客户
|
|
|
315
315
|
### 升级
|
|
316
316
|
|
|
317
317
|
```bash
|
|
318
|
-
dsh plugin --profile desktop add dsh-retrace@0.4.
|
|
318
|
+
dsh plugin --profile desktop add dsh-retrace@0.4.152
|
|
319
319
|
# 然后重启 DSH —— 插件不会热重载
|
|
320
320
|
```
|
|
321
321
|
|
|
@@ -334,7 +334,7 @@ dsh plugin --profile desktop add dsh-retrace@0.4.151
|
|
|
334
334
|
|
|
335
335
|
### 版本固定建议
|
|
336
336
|
|
|
337
|
-
请固定到确切版本(`dsh-retrace@0.4.
|
|
337
|
+
请固定到确切版本(`dsh-retrace@0.4.152`),并让 `dsh-log-contract` 解析到 `>=0.3.18`。
|
|
338
338
|
**不要在跨宿主升级时依赖 `^0.4` 这种范围**:这里的兼容性由**宿主的面**决定,光看 semver 不够。
|
|
339
339
|
|
|
340
340
|
---
|
|
@@ -43,16 +43,26 @@ export const CHECKPOINT_TICKET_TTL_MS = 120_000
|
|
|
43
43
|
export const CHECKPOINT_MAX_FILE_BYTES = 1024 * 1024
|
|
44
44
|
/** A pending checkpoint older than this is a crash leftover, not an operation. */
|
|
45
45
|
export const CHECKPOINT_PENDING_MAX_AGE_MS = 24 * 60 * 60 * 1000
|
|
46
|
+
/** 后台剪枝周期(启动之外的低频维护;只删超龄 pending,不动有效记录)。 */
|
|
47
|
+
export const CHECKPOINT_PENDING_PRUNE_INTERVAL_MS = 6 * 60 * 60 * 1000
|
|
46
48
|
|
|
47
49
|
const EXCLUDED_SEGMENTS = new Set(['.git', 'node_modules'])
|
|
48
50
|
const HEX64 = /^[0-9a-f]{64}$/
|
|
49
51
|
|
|
50
52
|
const sha256Of = (bytes) => createHash('sha256').update(bytes).digest('hex')
|
|
51
53
|
|
|
54
|
+
/**
|
|
55
|
+
* 字节 → 文本;二进制/非 UTF-8 ⇒ **稳定错误码 `binary-unsupported`**。
|
|
56
|
+
*
|
|
57
|
+
* 为什么要单独一个码:宿主 fs seam(0.1.7-rc.2 与 0.2.2-rc.2 两线)只有文本变更原语
|
|
58
|
+
* (`writeText`/`patchText`,见 docs/COMPAT.md 的“二进制文件”一节),二进制前像
|
|
59
|
+
* **没有官方回写 seam**。这里失败要让调用方/用户看到「二进制,无法回写」,而不是
|
|
60
|
+
* 一个含糊的 `unsupported`,更不能把乱码写回去。
|
|
61
|
+
*/
|
|
52
62
|
const textOf = (bytes) => {
|
|
53
63
|
const buffer = Buffer.from(bytes)
|
|
54
64
|
const text = buffer.toString('utf8')
|
|
55
|
-
if (text.includes('\0') || !Buffer.from(text).equals(buffer)) throw editorError('unsupported', 'binary-or-encoding')
|
|
65
|
+
if (text.includes('\0') || !Buffer.from(text).equals(buffer)) throw editorError('binary-unsupported', 'binary-or-encoding')
|
|
56
66
|
return text
|
|
57
67
|
}
|
|
58
68
|
|
|
@@ -564,9 +574,23 @@ export function createCheckpointRestore({
|
|
|
564
574
|
artifacts.push({ path: row.path, status: 'deleted' })
|
|
565
575
|
continue
|
|
566
576
|
}
|
|
567
|
-
const
|
|
577
|
+
const bytes = await preimages.objectStore.read(row.sha256)
|
|
568
578
|
const policy = ctx.sandboxPolicy?.resolve?.({ session })
|
|
569
|
-
|
|
579
|
+
const expected = row.version === null ? { kind: 'createIfAbsent' } : replaceIfVersion(row.version)
|
|
580
|
+
let text = null
|
|
581
|
+
try {
|
|
582
|
+
text = textOf(bytes)
|
|
583
|
+
} catch (error) {
|
|
584
|
+
if (error?.code !== 'binary-unsupported') throw error
|
|
585
|
+
// 二进制前像:**宿主有二进制写 seam 才写**(feature-detect,当前两线都没有)。
|
|
586
|
+
// 没有 ⇒ 显式 `failed/binary-unsupported`(不写乱码、也不假装成功)。
|
|
587
|
+
const writeBytes = typeof ctx.fs?.writeBytes === 'function' ? ctx.fs.writeBytes.bind(ctx.fs) : null
|
|
588
|
+
if (writeBytes === null) throw error
|
|
589
|
+
await writeBytes(row.target, bytes, expected, undefined, policy)
|
|
590
|
+
artifacts.push({ path: row.path, status: 'restored', via: 'bytes' })
|
|
591
|
+
continue
|
|
592
|
+
}
|
|
593
|
+
await ctx.fs.writeText(row.target, text, expected, undefined, policy)
|
|
570
594
|
artifacts.push({ path: row.path, status: 'restored' })
|
|
571
595
|
} catch (error) {
|
|
572
596
|
artifacts.push({ path: row.path, status: 'failed', reason: error?.code ?? 'write-failed' })
|
|
@@ -736,6 +760,20 @@ export function createCheckpointRestore({
|
|
|
736
760
|
return { sessionId, checkpoints }
|
|
737
761
|
}
|
|
738
762
|
|
|
763
|
+
/**
|
|
764
|
+
* **过期 pending 剪枝**(启动 / 定期 / 手动共用入口)。
|
|
765
|
+
* 判据在 `prunePending` 里:只删 `pending === true` 且超龄 —— 已提交记录
|
|
766
|
+
* 与新鲜 pending(正在进行的操作)一律不动;幂等(没东西可删就是 0)。
|
|
767
|
+
* @returns {Promise<{sessions:number, removed:number}>}
|
|
768
|
+
*/
|
|
769
|
+
async function pruneStalePending({ maxAgeMs = CHECKPOINT_PENDING_MAX_AGE_MS } = {}) {
|
|
770
|
+
const result = await preimages.pruneAllPending({ maxAgeMs, at: now() })
|
|
771
|
+
if (result.removed > 0) {
|
|
772
|
+
log(`retrace: pending 剪枝 → 清理 ${result.removed} 条超龄 pending(扫描 ${result.sessions} 个会话索引)`)
|
|
773
|
+
}
|
|
774
|
+
return result
|
|
775
|
+
}
|
|
776
|
+
|
|
739
777
|
/** GC = checkpoint refs + live undo tickets + artifact-store refCounts (never delete a pinned object). */
|
|
740
778
|
async function collectGarbage({ extraKeep = [] } = {}) {
|
|
741
779
|
let artifactRefs = []
|
|
@@ -764,6 +802,7 @@ export function createCheckpointRestore({
|
|
|
764
802
|
preview: envelope((args) => previewCheckpoint(String(args?.sessionId ?? ''), String(args?.versionId ?? ''))),
|
|
765
803
|
execute: envelope((args) => executeCheckpoint(args)),
|
|
766
804
|
collectGarbage,
|
|
805
|
+
pruneStalePending,
|
|
767
806
|
pruneTickets: () => { for (const [key, ticket] of tickets) if (ticket.expires <= now()) tickets.delete(key) },
|
|
768
807
|
}
|
|
769
808
|
}
|
package/lib/index.js
CHANGED
|
@@ -25,7 +25,7 @@ import { createRetraceHttpHandler, ROUTE_PREFIX } from './http.js'
|
|
|
25
25
|
import { createVersioningSeam } from './versioning.js'
|
|
26
26
|
import { createRollbackExecutor, createTrueRestore } from './rollback.js'
|
|
27
27
|
import { createPreimageStore } from './preimage-store.js'
|
|
28
|
-
import { createCheckpointRestore } from './checkpoint-restore.js'
|
|
28
|
+
import { createCheckpointRestore, CHECKPOINT_PENDING_PRUNE_INTERVAL_MS } from './checkpoint-restore.js'
|
|
29
29
|
import { createMarkerGuard } from './prewrite-guard.js'
|
|
30
30
|
import { createWatchdog } from './watchdog.js'
|
|
31
31
|
import { createBootPinRetry } from './boot-pin.js'
|
|
@@ -897,6 +897,14 @@ export function apply(ctx) {
|
|
|
897
897
|
logOnce(`autoCleanTitles:startup:${result.restored}:${result.skipped}:${result.failed}`,
|
|
898
898
|
`retrace: 启动标题自动清理完成 → 已清理 ${result.restored} / 跳过 ${result.skipped} / 失败 ${result.failed}(未驻留剩余 ${result.pending})`)
|
|
899
899
|
})
|
|
900
|
+
// 启动维护之二:清理**超龄 pending** 检查点(崩溃残留)。只删 pending 且超龄 ⇒
|
|
901
|
+
// 已提交记录与正在进行的 pending 不动(判据在 lib/preimage-store.js#prunePending)。
|
|
902
|
+
.then(async () => {
|
|
903
|
+
if (typeof checkpointRestore.pruneStalePending !== 'function') return
|
|
904
|
+
const pruned = await checkpointRestore.pruneStalePending()
|
|
905
|
+
logOnce(`prunePending:startup:${pruned.removed}`,
|
|
906
|
+
`retrace: 启动 pending 剪枝 → 清理 ${pruned.removed} 条超龄 pending(扫描 ${pruned.sessions} 个会话索引)`)
|
|
907
|
+
})
|
|
900
908
|
.catch((error) => log(`retrace: 启动标题自动清理异常(可见,不影响主功能): ${String(error?.message ?? error).slice(0, 120)}`))
|
|
901
909
|
}, 1200)
|
|
902
910
|
if (typeof autoCleanTimer?.unref === 'function') autoCleanTimer.unref()
|
|
@@ -904,9 +912,24 @@ export function apply(ctx) {
|
|
|
904
912
|
log(`retrace: 启动标题自动清理调度失败(可见): ${String(error?.message ?? error).slice(0, 120)}`)
|
|
905
913
|
}
|
|
906
914
|
|
|
915
|
+
// 定期维护:每 6h 剪一次超龄 pending(懒清理只覆盖"被点开的会话",崩溃残留靠这里兜底)。
|
|
916
|
+
let pendingPruneTimer = null
|
|
917
|
+
try {
|
|
918
|
+
pendingPruneTimer = setInterval(() => {
|
|
919
|
+
if (typeof checkpointRestore.pruneStalePending !== 'function') return
|
|
920
|
+
checkpointRestore.pruneStalePending()
|
|
921
|
+
.then((pruned) => { if (pruned.removed > 0) logOnce(`prunePending:tick:${pruned.removed}`, `retrace: 定期 pending 剪枝 → 清理 ${pruned.removed} 条超龄 pending(扫描 ${pruned.sessions} 个会话索引)`) })
|
|
922
|
+
.catch((error) => log(`retrace: 定期 pending 剪枝失败(可见,不影响主功能): ${String(error?.message ?? error).slice(0, 120)}`))
|
|
923
|
+
}, CHECKPOINT_PENDING_PRUNE_INTERVAL_MS)
|
|
924
|
+
if (typeof pendingPruneTimer?.unref === 'function') pendingPruneTimer.unref()
|
|
925
|
+
} catch (error) {
|
|
926
|
+
log(`retrace: 定期 pending 剪枝调度失败(可见): ${String(error?.message ?? error).slice(0, 120)}`)
|
|
927
|
+
}
|
|
928
|
+
|
|
907
929
|
const disposers = [
|
|
908
930
|
() => sessionCreatedDispose?.(),
|
|
909
931
|
() => { if (autoCleanTimer !== null) { try { clearTimeout(autoCleanTimer) } catch { /* 已触发 */ } autoCleanTimer = null } },
|
|
932
|
+
() => { if (pendingPruneTimer !== null) { try { clearInterval(pendingPruneTimer) } catch { /* 已触发 */ } pendingPruneTimer = null } },
|
|
910
933
|
|
|
911
934
|
// recall 语义 = 遮蔽目标轮及之后全部(编辑=从此处分叉)
|
|
912
935
|
// ——不再只遮蔽目标轮(缺陷①断层);tail 在官方 foldSurface
|
package/lib/preimage-store.js
CHANGED
|
@@ -228,6 +228,35 @@ export function createPreimageStore({
|
|
|
228
228
|
return removed
|
|
229
229
|
}
|
|
230
230
|
|
|
231
|
+
/**
|
|
232
|
+
* Prune stale `pending` records for **every known session** (crash leftovers).
|
|
233
|
+
*
|
|
234
|
+
* 为什么需要"全量"版本:`prunePending(sessionId)` 只在用户**打开某个会话的**
|
|
235
|
+
* 读档/预览时才跑(懒清理)⇒ 崩溃残留会一直躺在盘上直到那个会话被点开。
|
|
236
|
+
* 启动/定期维护走这里(枚举 `checkpoints/*.json`,逐个调用同一实现,
|
|
237
|
+
* 判据不变:只删 `pending===true` 且超龄的记录 —— 已提交记录与新鲜 pending 一律不动)。
|
|
238
|
+
* @returns {Promise<{sessions:number, removed:number}>}
|
|
239
|
+
*/
|
|
240
|
+
async function pruneAllPending({ maxAgeMs = 24 * 60 * 60 * 1000, at = now() } = {}) {
|
|
241
|
+
let names = []
|
|
242
|
+
try { names = await readdir(checkpointsRoot) } catch { return { sessions: 0, removed: 0 } }
|
|
243
|
+
let sessions = 0
|
|
244
|
+
let removed = 0
|
|
245
|
+
for (const name of names) {
|
|
246
|
+
if (!name.endsWith('.json')) continue
|
|
247
|
+
try {
|
|
248
|
+
const parsed = JSON.parse(await readFile(join(checkpointsRoot, name), 'utf8'))
|
|
249
|
+
const sessionId = typeof parsed?.sessionId === 'string' && parsed.sessionId !== '' ? parsed.sessionId : null
|
|
250
|
+
if (sessionId === null) continue
|
|
251
|
+
sessions += 1
|
|
252
|
+
removed += await prunePending(sessionId, { maxAgeMs, at })
|
|
253
|
+
} catch (error) {
|
|
254
|
+
log(`retrace: pending 剪枝跳过不可读的检查点索引(${name}): ${String(error)}`)
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
return { sessions, removed }
|
|
258
|
+
}
|
|
259
|
+
|
|
231
260
|
/** Refuse to collect while another append is mid-flight in this process. */
|
|
232
261
|
async function settled() {
|
|
233
262
|
await Promise.all([...tails.values()])
|
|
@@ -303,6 +332,7 @@ export function createPreimageStore({
|
|
|
303
332
|
updateRecord,
|
|
304
333
|
removeRecord,
|
|
305
334
|
prunePending,
|
|
335
|
+
pruneAllPending,
|
|
306
336
|
retain,
|
|
307
337
|
collect,
|
|
308
338
|
now,
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-retrace",
|
|
3
3
|
"description": "Retrace · 回溯 — Recall, edit-and-resend, regenerate, and conversation/artifact versioning (timeline, rollback, fork graph) for DeepSeek Harness — Web and Desktop",
|
|
4
|
-
"version": "0.4.
|
|
4
|
+
"version": "0.4.152",
|
|
5
5
|
"packageManager": "pnpm@11.7.0",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"main": "lib/index.js",
|
|
@@ -69,7 +69,7 @@
|
|
|
69
69
|
},
|
|
70
70
|
"target": {
|
|
71
71
|
"package": "dsh-retrace",
|
|
72
|
-
"version": "0.4.
|
|
72
|
+
"version": "0.4.152",
|
|
73
73
|
"host": ">=0.1.7-rc.2 <0.3.0-0 || >=0.2.2-0 <0.3.0-0"
|
|
74
74
|
},
|
|
75
75
|
"changes": [
|