@aalis/plugin-checkpoint 0.14.0 → 0.16.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/dist/config.d.ts +26 -24
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +23 -18
- package/dist/config.js.map +1 -1
- package/dist/index.d.ts +12 -7
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +52 -85
- package/dist/index.js.map +1 -1
- package/dist/locales/en.d.ts +30 -0
- package/dist/locales/en.d.ts.map +1 -0
- package/dist/locales/en.js +30 -0
- package/dist/locales/en.js.map +1 -0
- package/dist/service.d.ts +60 -86
- package/dist/service.d.ts.map +1 -1
- package/dist/service.js +190 -123
- package/dist/service.js.map +1 -1
- package/dist/texts.d.ts +59 -0
- package/dist/texts.d.ts.map +1 -0
- package/dist/texts.js +33 -0
- package/dist/texts.js.map +1 -0
- package/package.json +21 -10
package/dist/service.d.ts
CHANGED
|
@@ -1,151 +1,125 @@
|
|
|
1
|
+
import type { CheckpointService, RollbackResult, RollbackWithChatResult } from '@aalis/api-checkpoint';
|
|
1
2
|
import type { MemoryService } from '@aalis/api-memory';
|
|
2
3
|
import { type StorageService } from '@aalis/api-storage';
|
|
3
|
-
import type { Logger,
|
|
4
|
+
import type { Logger, ServiceSelection } from '@aalis/core';
|
|
5
|
+
import { type TextRef } from '@aalis/schema-i18n';
|
|
4
6
|
import { type CheckpointConfig } from './config.js';
|
|
5
|
-
|
|
6
|
-
* Checkpoint 服务
|
|
7
|
-
*
|
|
8
|
-
* 在 LLM 一次回合（assistant turn）期间记录受控存储中的写入/删除/重命名操作（data / tmp / pluginData /
|
|
9
|
-
* logs 这几类共享根与临时根除外，见 beforeMutate），
|
|
10
|
-
* 在改动发生前自动备份原始文件内容，使用户可以从 WebUI 一键回滚整轮操作。
|
|
11
|
-
*
|
|
12
|
-
* 协作模型：
|
|
13
|
-
* - plugin-storage-local 在执行 writeFile/delete/rename 之前先探测 checkpoint 服务，
|
|
14
|
-
* 在场就调它的 `beforeMutate(...)` 留一次快照机会。
|
|
15
|
-
* - 本服务通过 hooks `agent:input:before` / `agent:turn:after` 维护「当前回合」状态。
|
|
16
|
-
* - exec / exec_background / run_* 等命令类工具直接调用系统命令，不在本服务保护范围内
|
|
17
|
-
* （前端 UI 标注「未保护」）。
|
|
18
|
-
*/
|
|
19
|
-
export interface CheckpointService {
|
|
20
|
-
/** 探测：是否在某个回合内（storage-local 提早判断以避免无谓 stat） */
|
|
21
|
-
isActive(): boolean;
|
|
22
|
-
/**
|
|
23
|
-
* 在 storage 即将修改 uri 时调用。本调用是 op="write"|"delete"|"rename" 之前的一次性快照机会。
|
|
24
|
-
* 如果同一 uri 在当前回合内已被快照过，则不再备份内容（保留最早的原始内容）；
|
|
25
|
-
* 但 op='rename' 仍会补记一条不带 blob 的条目，否则「先改写再移走」的移动会整条丢失。
|
|
26
|
-
* loadOriginal 是按需读取原始内容的闭包；首次需要快照时才调用。
|
|
27
|
-
* toUri 仅 op='rename' 有意义：改动后的目标 URI，回滚时据它把文件原路移回
|
|
28
|
-
* （缺省则退化为「只把原内容写回源路径」，目标端会留一份重复）。
|
|
29
|
-
*/
|
|
30
|
-
beforeMutate(uri: string, op: 'write' | 'delete' | 'rename', loadOriginal: () => Promise<{
|
|
31
|
-
data: Buffer;
|
|
32
|
-
size: number;
|
|
33
|
-
} | null>, toUri?: string): Promise<void>;
|
|
34
|
-
/** 列出某个 session 的所有回合 checkpoint */
|
|
35
|
-
listTurns(sessionId: string): Promise<TurnSummary[]>;
|
|
36
|
-
/** 读取某回合 manifest */
|
|
37
|
-
getManifest(sessionId: string, turnId: string): Promise<TurnManifest | null>;
|
|
38
|
-
/** 回滚某回合（恢复 / 删除 / 重命名复原）。返回受影响文件计数 */
|
|
39
|
-
rollback(sessionId: string, turnId: string): Promise<RollbackResult>;
|
|
40
|
-
/** 回滚某回合并同步删除本轮对话消息与向量条目 */
|
|
41
|
-
rollbackWithChat(sessionId: string, turnId: string): Promise<RollbackWithChatResult>;
|
|
42
|
-
/** 清除某会话的所有 checkpoint（/clear 与 deleteSession 调用）。幂等；不存在也返回 0。 */
|
|
43
|
-
clearSession(sessionId: string): Promise<number>;
|
|
44
|
-
/** 清除全部 checkpoint（/clear all 调用）。幂等。 */
|
|
45
|
-
clearAll(): Promise<number>;
|
|
46
|
-
}
|
|
47
|
-
export interface CheckpointFileRecord {
|
|
7
|
+
interface CheckpointFileRecord {
|
|
48
8
|
uri: string;
|
|
49
|
-
/** write=覆盖已有, write-new=新创建, delete=删除, rename
|
|
9
|
+
/** write=覆盖已有, write-new=新创建, delete=删除, rename=改名或移动 */
|
|
50
10
|
action: 'write' | 'write-new' | 'delete' | 'rename';
|
|
51
|
-
/** rename 的目标 URI
|
|
11
|
+
/** rename 的目标 URI（回滚时原路移回；存储实现没给目标时缺省） */
|
|
52
12
|
toUri?: string;
|
|
53
|
-
/**
|
|
13
|
+
/** 原始大小（有快照时） */
|
|
54
14
|
originalSize?: number;
|
|
55
|
-
/**
|
|
15
|
+
/** 备份文件名（相对于回合目录） */
|
|
56
16
|
blob?: string;
|
|
57
|
-
/**
|
|
58
|
-
|
|
17
|
+
/**
|
|
18
|
+
* 没有备份的原因（过大、读取失败、目录等），这一条不可回滚。可以是文字对象（旧清单是字符串），回滚时原样放进
|
|
19
|
+
* RollbackResult.errors
|
|
20
|
+
*/
|
|
21
|
+
skipped?: string | TextRef;
|
|
59
22
|
}
|
|
23
|
+
/** 一轮的清单，提交时落盘为回合目录下的 manifest.json */
|
|
60
24
|
export interface TurnManifest {
|
|
25
|
+
/** 回合 id，与 agent 的回合 id 相同 */
|
|
61
26
|
turnId: string;
|
|
62
27
|
sessionId: string;
|
|
63
28
|
startedAt: number;
|
|
64
29
|
endedAt?: number;
|
|
65
30
|
files: CheckpointFileRecord[];
|
|
66
|
-
/**
|
|
31
|
+
/** 这一轮对话消息的时间戳（只记属于这一轮的，见 commitTurn），rollbackWithChat 据此删除消息与向量条目 */
|
|
67
32
|
messageTimestamps?: number[];
|
|
68
33
|
}
|
|
69
|
-
|
|
34
|
+
/** 回合列表的一行（listTurns） */
|
|
35
|
+
interface TurnSummary {
|
|
70
36
|
turnId: string;
|
|
71
37
|
sessionId: string;
|
|
72
38
|
startedAt: number;
|
|
73
39
|
endedAt?: number;
|
|
74
40
|
fileCount: number;
|
|
75
|
-
/**
|
|
76
|
-
execUsed?: boolean;
|
|
77
|
-
/** 摘要预览（前 3 个文件 URI） */
|
|
41
|
+
/** 前 3 个文件的 URI */
|
|
78
42
|
filesPreview: string[];
|
|
79
43
|
}
|
|
80
|
-
export interface RollbackResult {
|
|
81
|
-
ok: boolean;
|
|
82
|
-
restored: string[];
|
|
83
|
-
deleted: string[];
|
|
84
|
-
errors: Array<{
|
|
85
|
-
uri: string;
|
|
86
|
-
reason: string;
|
|
87
|
-
}>;
|
|
88
|
-
}
|
|
89
|
-
export interface RollbackWithChatResult extends RollbackResult {
|
|
90
|
-
/** 实际从 memory 中删除的消息条数 */
|
|
91
|
-
deletedMessages: number;
|
|
92
|
-
/** chat 删除是否成功；若失败，errors 也会记录原因 */
|
|
93
|
-
chatDeleted: boolean;
|
|
94
|
-
}
|
|
95
44
|
interface ServiceConfig {
|
|
96
45
|
rootUri: string;
|
|
97
46
|
maxFileSize: number;
|
|
98
47
|
keepSessions: number;
|
|
99
|
-
|
|
48
|
+
keepTurns: number;
|
|
100
49
|
}
|
|
101
50
|
/**
|
|
102
|
-
*
|
|
51
|
+
* Checkpoint 服务实现
|
|
52
|
+
*
|
|
53
|
+
* 在一轮对话期间记录受控存储中的写入/删除/重命名操作（data / tmp / cache / pluginData /
|
|
54
|
+
* logs / paper / public / self 这几类共享根、临时根、白纸根、公开根与 self 根除外，见 beforeMutate），
|
|
55
|
+
* 在改动发生前自动备份原始文件内容，使用户可以一键回滚整轮操作。
|
|
56
|
+
*
|
|
57
|
+
* 协作模型：
|
|
58
|
+
* - plugin-storage-local 在执行 writeFile/delete/rename 之前先探测 checkpoint 服务，
|
|
59
|
+
* 在场就调它的 `beforeMutate(...)` 留一次快照机会。
|
|
60
|
+
* - 本插件在 `agent:turn:before` 里用 agent 给的 turnId 把这一轮包进 `runTurn`：回合的异步上下文里发生的改动
|
|
61
|
+
* 记进这一轮，回合跑完（含被下游拦下、出错）即提交。
|
|
62
|
+
* - 命令与外部工具的副作用不经存储，不在本服务保护范围内（回滚对话框写明）。
|
|
103
63
|
*/
|
|
104
64
|
export declare class CheckpointServiceImpl implements CheckpointService {
|
|
105
65
|
private readonly cfg;
|
|
106
66
|
private readonly logger;
|
|
107
67
|
private readonly storage;
|
|
108
68
|
/**
|
|
109
|
-
*
|
|
110
|
-
*
|
|
69
|
+
* 进行中的回合，按 turnId 记。几轮可以同时在跑（不同会话的回合并发），
|
|
70
|
+
* 改动按写入时所在的异步上下文归属到其中一轮，见 {@link scope}。
|
|
111
71
|
*/
|
|
112
|
-
private turns;
|
|
113
|
-
/**
|
|
114
|
-
private readonly
|
|
72
|
+
private readonly turns;
|
|
73
|
+
/** 回合的异步上下文：runTurn 里跑的一切（钩子、工具、它们触发的存储写入）都带着这一轮 */
|
|
74
|
+
private readonly scope;
|
|
115
75
|
/** 读失败的告警记录：位置（会话目录或 manifest URI）→ 已告警过的原因 */
|
|
116
76
|
private readonly readFailures;
|
|
117
77
|
constructor(cfg: ServiceConfig, logger: Logger, storage: StorageService);
|
|
118
|
-
|
|
119
|
-
|
|
78
|
+
/**
|
|
79
|
+
* 在一轮里跑 fn：fn 的异步上下文里发生的存储改动记进这一轮，fn 结束（含抛错）即提交。
|
|
80
|
+
* 开始与结束在同一次调用里配对，同一会话并发的几轮互不结束对方。提交失败只告警：回复已经发出，
|
|
81
|
+
* 这一轮只是不能回滚。
|
|
82
|
+
*/
|
|
83
|
+
runTurn<T>(turnId: string, sessionId: string, fn: () => Promise<T>): Promise<T>;
|
|
120
84
|
/** 进程退出前提交所有活跃回合，避免未结束回合丢失。 */
|
|
121
85
|
flushAll(): Promise<void>;
|
|
122
|
-
/**
|
|
86
|
+
/**
|
|
87
|
+
* 提交一个回合：补 endedAt + 抓消息时间戳 + 落盘 manifest + 触发 GC。无改动则跳过。
|
|
88
|
+
* 消息只记时间窗里属于这一轮的：元数据的回合 id 是这一轮的（输入、工具调用组、回复、带回合 id 的出站记录与投递失败记录，
|
|
89
|
+
* 经工具发出的也带它）。同一时间窗里别的来源的输入与别的回合的产出不记，回滚时不连带删掉
|
|
90
|
+
*/
|
|
123
91
|
private commitTurn;
|
|
124
|
-
/** 标记某会话当前回合调用过 exec / exec_background / run_* 等命令类工具，UI 端会提示「部分未保护」 */
|
|
125
|
-
markExecUsed(sessionId: string): void;
|
|
126
|
-
isActive(): boolean;
|
|
127
92
|
beforeMutate(uri: string, op: 'write' | 'delete' | 'rename', loadOriginal: () => Promise<{
|
|
128
93
|
data: Buffer;
|
|
129
94
|
size: number;
|
|
130
95
|
} | null>, toUri?: string): Promise<void>;
|
|
131
96
|
listTurns(sessionId: string): Promise<TurnSummary[]>;
|
|
97
|
+
/** 某会话已提交回合的清单，读不出来的回合跳过（并留痕） */
|
|
98
|
+
private manifests;
|
|
132
99
|
getManifest(sessionId: string, turnId: string): Promise<TurnManifest | null>;
|
|
133
100
|
/**
|
|
134
|
-
*
|
|
135
|
-
* storage 不在线或 manifest
|
|
101
|
+
* 读失败留痕：「不存在」不算失败；其它原因告警，但同一位置同一原因只记一次——每次回滚都要读这个会话的全部清单，
|
|
102
|
+
* storage 不在线或 manifest 损坏时不能每次都记一条。读通（或确认不存在）即清掉记录，之后再失败会再记。
|
|
136
103
|
*/
|
|
137
104
|
private readFailed;
|
|
138
105
|
rollback(sessionId: string, turnId: string): Promise<RollbackResult>;
|
|
106
|
+
/**
|
|
107
|
+
* 这一轮改过、同一会话里另有回合也改过的文件（含移动的目标端），见 RollbackResult.alsoChangedBy。
|
|
108
|
+
* 在这一轮开始前就已结束的回合不算；已提交的与还在跑的回合都算。时间戳只到毫秒，结束与开始落在同一毫秒的
|
|
109
|
+
* 分不出先后，按算处理：多列一轮只是多一句如实的提示，漏列会让回滚悄悄撤掉别人的改动。
|
|
110
|
+
*/
|
|
111
|
+
private alsoChangedBy;
|
|
139
112
|
private _memory?;
|
|
140
113
|
private _emitMessagesDeleted?;
|
|
141
114
|
private _emitHistoryChanged?;
|
|
142
115
|
/** 注入聊天回滚所需的依赖：memory 引用（每次用时解析当前提供者）+ 事件发出器 */
|
|
143
116
|
setChatRollbackDeps(deps: {
|
|
144
|
-
memory:
|
|
117
|
+
memory: ServiceSelection<MemoryService>;
|
|
145
118
|
emitMessagesDeleted: (sessionId: string, timestamps: number[]) => void;
|
|
146
119
|
emitHistoryChanged: (sessionId: string) => void;
|
|
147
120
|
}): void;
|
|
148
121
|
rollbackWithChat(sessionId: string, turnId: string): Promise<RollbackWithChatResult>;
|
|
122
|
+
/** 提交回合后清理：这个会话超出 keepTurns 的最旧回合连同备份删掉；会话目录超出 keepSessions 时删最旧的会话 */
|
|
149
123
|
private gc;
|
|
150
124
|
private turnDir;
|
|
151
125
|
/** uri 是否落在本插件自己的 checkpoint 根下（blob / manifest） */
|
package/dist/service.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}
|