feat: journal reviewed multi-file changes and recover interrupted batches

This commit is contained in:
Agent Workbench Dev
2026-10-29 18:45:05 +08:00
parent c89cb2d593
commit 5d03af968c
20 changed files with 741 additions and 16 deletions
+349
View File
@@ -0,0 +1,349 @@
import fs from 'node:fs';
import path from 'node:path';
import { randomUUID } from 'node:crypto';
import { safePath, excludedFromInventory, hash } from '../../server/files.mjs';
import { inspectProject } from '../project-inspector.mjs';
import { assertChangeSetsResolved, CHANGE_SET_OPEN } from '../../shared/contracts/change-sets.mjs';
const at = () => new Date().toISOString();
const conflict = message => Object.assign(new Error(message), { status: 409 });
const key = value => process.platform === 'win32' ? value.toLowerCase() : value;
const gitBaseline = inspection => ({ available: inspection.git.available, head: inspection.git.head ?? null, branch: inspection.git.branch ?? null });
const sealed = set => ({ id: set.id, sessionId: set.sessionId, projectId: set.projectId, taskId: set.taskId, runId: set.runId,
root: set.root, baseline: set.baseline, files: set.files.map(file => ({ changeId: file.changeId, path: file.path,
baseExists: file.baseExists, baseSha256: file.baseSha256, sha256: file.sha256, baseBytes: file.baseBytes, bytes: file.bytes,
mode: file.mode, reason: file.reason, sourceRunId: file.sourceRunId, snapshotArtifactId: file.snapshotArtifactId })) });
const observationHash = observations => hash(Buffer.from(JSON.stringify(observations.map(file =>
({ path: file.path, state: file.state, exists: file.exists, actualSha256: file.actualSha256, problem: file.problem ?? null })))));
// A batch rejects links and platform aliases rather than treating two names as
// independent files. The project root was canonicalized when it was opened.
function targetFor(project, relative) {
const target = safePath(project, relative, true), portable = path.relative(project.root, target).replaceAll('\\', '/');
if (!portable || excludedFromInventory(portable)) throw conflict('变更集只能包含项目范围内的普通源码文件。');
for (const part of portable.split('/')) if (process.platform === 'win32'
&& (/[. ]$/.test(part) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i.test(part))) throw conflict('变更集路径含Windows设备名或不唯一的路径别名。');
let current = project.root;
for (const part of portable.split('/')) {
current = path.join(current, part);
try {
const stat = fs.lstatSync(current);
if (stat.isSymbolicLink() || stat.isFile() && stat.nlink > 1) throw conflict('变更集目标不能经过链接或共享硬链接文件。');
} catch (error) { if (error.code !== 'ENOENT') throw error; }
}
return { target, path: portable };
}
function validatePaths(project, files) {
const seen = [];
for (const file of files) {
const target = targetFor(project, file.path), identity = key(target.path);
if (seen.some(value => value === identity || value.startsWith(identity + '/') || identity.startsWith(value + '/'))) {
throw conflict('同一变更集不能重复修改实际路径,也不能包含文件与其子路径。');
}
seen.push(identity);
}
}
function observe(project, file) {
try {
const { target } = targetFor(project, file.path);
let stat;
try { stat = fs.lstatSync(target); } catch (error) { if (error.code !== 'ENOENT') throw error; }
if (stat && (!stat.isFile() || stat.size > 4 * 1024 * 1024)) throw new Error('目标已不是有界普通文件。');
const exists = !!stat, actualSha256 = exists ? hash(fs.readFileSync(target)) : null;
const state = exists === file.baseExists && actualSha256 === file.baseSha256 ? 'before'
: exists && actualSha256 === file.sha256 ? 'after' : 'external';
return { path: file.path, state, exists, actualSha256 };
} catch (error) { return { path: file.path, state: 'unavailable', exists: null, actualSha256: null, problem: error.message }; }
}
function base64(value) {
if (typeof value !== 'string') throw conflict('变更集快照内容无效。');
const bytes = Buffer.from(value, 'base64');
if (bytes.toString('base64') !== value) throw conflict('变更集快照编码无效。');
return bytes;
}
export class ChangeSetManager {
constructor(store, { projectBusy = () => false, faultInjector = null } = {}) {
this.store = store; this.projectBusy = projectBusy; this.faultInjector = faultInjector;
this.active = new Map(); this.projects = new Map();
}
projectActive(id) { return this.projects.has(id); }
isActive(id) { return [...this.active.values()].some(value => value.sessionId === id); }
async cut(phase, set, index = null) {
await this.faultInjector?.(phase, set, index);
await new Promise(resolve => setImmediate(resolve));
}
save(session, set, phase) { this.store.save(session, { type: 'change_set.' + phase, detail: { changeSetId: set.id } }); }
requireIdle(session, { source = 'user', exceptId = null, includePrepared = false } = {}) {
if (this.projectActive(session.projectId) || this.projectBusy(session.projectId, source === 'agent' ? session.id : null)) {
throw conflict('同一项目正在执行任务、检查、提交或文件批次,请等待结束后再操作。');
}
assertChangeSetsResolved(this.store, session.projectId, { exceptId, includePrepared });
}
own(session, id, fingerprint = null, { current = false } = {}) {
const set = this.store.owned('change_set', id, session.id);
if (current && set.taskId !== session.taskId) throw conflict('变更集属于此前Task,请在所属任务中核对。');
if (fingerprint !== null && fingerprint !== set.fingerprint) throw conflict('审查指纹已变化,请重新打开这个变更集。');
return set;
}
snapshots(session, set, { pending = false } = {}) {
const project = this.store.project(session.projectId);
if (set.root !== project.root || hash(Buffer.from(JSON.stringify(sealed(set)))) !== set.fingerprint) throw conflict('变更集封存信息校验失败,请核对原批次。');
validatePaths(project, set.files);
return set.files.map(file => {
const change = session.changes.find(value => value.id === file.changeId);
if (!change || change.taskId !== set.taskId || change.runId !== file.sourceRunId || targetFor(project, change.path).path !== file.path
|| change.baseExists !== file.baseExists || change.baseSha256 !== file.baseSha256 || change.sha256 !== file.sha256
|| hash(Buffer.from(change.content, 'utf8')) !== file.sha256 || change.reason !== file.reason
|| pending && (change.status !== 'pending' || change.changeSetId !== set.id)) throw conflict('变更集中的原提案已变化,请重新审查。');
const artifact = this.store.owned('artifact', file.snapshotArtifactId, session.id);
if (artifact.kind !== 'change-set-snapshot' || artifact.taskId !== set.taskId || artifact.runId !== set.runId) throw conflict('变更集快照不属于原Task/Run。');
const snapshot = JSON.parse(this.store.artifactStore.read(artifact));
if (snapshot.schemaVersion !== 1 || snapshot.changeSetId !== set.id || snapshot.changeId !== file.changeId
|| snapshot.path !== file.path || snapshot.mode !== file.mode || snapshot.sourceRunId !== file.sourceRunId) throw conflict('变更集快照身份校验失败。');
const before = file.baseExists ? base64(snapshot.before) : null, after = base64(snapshot.after);
if (file.baseExists ? hash(before) !== file.baseSha256 || before.length !== file.baseBytes : snapshot.before !== null || file.baseSha256 !== null) throw conflict('变更集原字节快照校验失败。');
if (hash(after) !== file.sha256 || after.length !== file.bytes) throw conflict('变更集建议字节快照校验失败。');
return { before, after };
});
}
inspect(session, set) {
const project = this.store.project(session.projectId), observations = set.files.map(file => {
const value = observe(project, file);
if (set.attemptedAt && !file.writeAttempted && value.state === 'after') value.state = 'external';
return value;
});
set.observations = observations; set.observationFingerprint = observationHash(observations); set.verifiedAt = at();
for (let index = 0; index < set.files.length; index++) set.files[index].state = observations[index].state;
return observations;
}
async prepare(session, changeIds, { source = 'user' } = {}) {
if (!Array.isArray(changeIds) || !changeIds.length || changeIds.length > 32 || new Set(changeIds).size !== changeIds.length) throw conflict('变更集需要1到32个不同的提案ID。');
this.requireIdle(session, { source });
const task = this.store.owned('task', session.taskId, session.id), run = this.store.owned('run', session.runId, session.id);
const existing = [...this.store.core.change_set.values()].find(value => value.projectId === session.projectId && value.status === 'prepared');
if (existing) {
if (existing.sessionId === session.id && existing.taskId === task.id
&& JSON.stringify(existing.files.map(file => file.changeId).sort()) === JSON.stringify([...changeIds].sort())) {
this.snapshots(session, existing, { pending: true }); return existing;
}
throw conflict('项目已有封存的待审查变更集,请先应用或撤销原批次。');
}
const changes = changeIds.map(id => session.changes.find(value => value.id === id));
if (changes.some(value => !value || value.taskId !== task.id || this.store.core.run.get(value.runId)?.taskId !== task.id || value.status !== 'pending'
|| value.changeSetId && CHANGE_SET_OPEN.has(this.store.core.change_set.get(value.changeSetId)?.status))) throw conflict('变更集只能封存当前Task的待审查提案。');
const project = this.store.project(session.projectId);
validatePaths(project, changes);
const temporaryId = randomUUID(); this.projects.set(project.id, temporaryId);
try {
const inspection = await inspectProject(project);
if (session.taskId !== task.id || session.runId !== run.id) throw conflict('准备变更集期间任务已切换。');
const set = { id: randomUUID(), sessionId: session.id, projectId: project.id, taskId: task.id, runId: run.id, root: project.root,
schemaVersion: 1, status: 'prepared', requiresVerification: false, source, createdAt: at(), baseline: gitBaseline(inspection), files: [],
policy: 'reviewed-byte-snapshots', summary: '整批范围已封存,项目文件尚未改变。' };
let budget = 0;
const snapshots = changes.map(change => {
const { target, path: portable } = targetFor(project, change.path), observation = observe(project, change);
if (observation.state !== 'before') throw conflict('文件基线已变化,未准备批次:' + portable);
const before = change.baseExists ? fs.readFileSync(target) : null, after = Buffer.from(change.content, 'utf8');
if (hash(after) !== change.sha256 || before && hash(before) !== change.baseSha256) throw conflict('提案内容或原文件已经变化:' + portable);
budget += (before?.length ?? 0) + after.length;
if (budget > 4 * 1024 * 1024) throw conflict('变更集原文与建议内容合计超过4MB。');
return { change, portable, before, after, mode: before ? fs.statSync(target).mode & 0o777 : 0o644 };
});
for (const { change, portable, before, after, mode } of snapshots) {
const artifact = this.store.artifactStore.write(session, run, { schemaVersion: 1, changeSetId: set.id, changeId: change.id,
path: portable, mode, sourceRunId: change.runId, before: before?.toString('base64') ?? null, after: after.toString('base64') }, { kind: 'change-set-snapshot' });
this.store.core.artifact.set(artifact.id, artifact);
set.files.push({ changeId: change.id, path: portable, baseExists: change.baseExists, baseSha256: change.baseSha256, sha256: change.sha256,
baseBytes: before?.length ?? 0, bytes: after.length, mode, reason: change.reason, additions: change.additions, deletions: change.deletions,
sourceRunId: change.runId, snapshotArtifactId: artifact.id, state: 'before', writeAttempted: false, restoreAttempted: false });
change.changeSetId = set.id;
}
set.fingerprint = hash(Buffer.from(JSON.stringify(sealed(set))));
this.store.putRecord('change_set', session, set, 'change_set.prepared');
await this.cut('prepared', set);
return set;
} finally { this.projects.delete(project.id); }
}
claim(session, set) {
const operation = { sessionId: session.id, projectId: session.projectId, controller: new AbortController(), promise: null };
this.projects.set(session.projectId, set.id); this.active.set(set.id, operation); return operation;
}
release(set) { this.projects.delete(set.projectId); this.active.delete(set.id); }
async start(session, id, fingerprint) {
const set = this.own(session, id, fingerprint, { current: true });
if (typeof fingerprint !== 'string' || set.status !== 'prepared' || set.attemptedAt) throw conflict('这个批次已执行或尚未提交原审查指纹,不能重复应用。');
this.requireIdle(session, { exceptId: set.id });
const operation = this.claim(session, set);
try {
const snapshots = this.snapshots(session, set, { pending: true });
const project = this.store.project(session.projectId), inspection = await inspectProject(project);
if (set.taskId !== session.taskId || JSON.stringify(gitBaseline(inspection)) !== JSON.stringify(set.baseline)) throw conflict('任务或Git HEAD/分支已变化,未写入任何文件。');
if (this.inspect(session, set).some(value => value.state !== 'before')) throw conflict('整批文件基线检查失败,未写入任何文件。');
set.status = 'applying'; set.attemptedAt = at(); set.direction = 'apply'; set.originalSessionStatus = session.status;
set.summary = '整批预检通过,正在记录逐文件写入。';
this.save(session, set, 'application_started');
operation.promise = this.execute(session, set, snapshots, operation).finally(() => this.release(set));
operation.promise.catch(() => {});
return { set, promise: operation.promise };
} catch (error) {
this.release(set);
if (!set.attemptedAt) { set.status = 'stale'; set.summary = '只读预检未通过,项目未写入:' + error.message; this.save(session, set, 'preflight_failed'); }
throw error;
}
}
async replace(session, set, index, bytes, direction) {
const project = this.store.project(session.projectId), file = set.files[index], expected = direction === 'apply' ? 'before' : 'after';
if (observe(project, file).state !== expected) throw conflict('目标在写入前变化,保留当前文件:' + file.path);
const { target } = targetFor(project, file.path);
if (bytes === null) {
if (observe(project, file).state !== expected) throw conflict('新文件在删除前变化,保留当前内容:' + file.path);
fs.unlinkSync(target);
} else {
fs.mkdirSync(path.dirname(target), { recursive: true }); targetFor(project, file.path);
const temporary = path.join(path.dirname(target), '.awb-' + set.id + '-' + index + '-' + direction + '.tmp');
let owned = false;
try {
if (fs.existsSync(temporary)) {
const stat = fs.lstatSync(temporary);
if (!stat.isFile() || stat.isSymbolicLink() || stat.size !== bytes.length || hash(fs.readFileSync(temporary)) !== hash(bytes)) {
throw conflict('遗留临时文件不属于已封存字节,保留该文件:' + file.path);
}
owned = true;
} else {
const handle = fs.openSync(temporary, 'wx', file.mode); owned = true;
try { fs.writeFileSync(handle, bytes); fs.fsyncSync(handle); } finally { fs.closeSync(handle); }
}
fs.chmodSync(temporary, file.mode);
await this.cut(direction === 'apply' ? 'staged' : 'restore_staged', set, index);
targetFor(project, file.path);
if (observe(project, file).state !== expected) throw conflict('目标在替换前变化,保留当前内容:' + file.path);
fs.renameSync(temporary, target); owned = false;
} finally {
if (owned && fs.existsSync(temporary) && !fs.lstatSync(temporary).isSymbolicLink() && hash(fs.readFileSync(temporary)) === hash(bytes)) fs.unlinkSync(temporary);
}
}
await this.cut(direction === 'apply' ? 'replaced' : 'restored', set, index);
if (observe(project, file).state !== (direction === 'apply' ? 'after' : 'before')) throw conflict('文件替换后发生变化,请核对:' + file.path);
}
settle(session, set, observations, direction) {
const complete = direction === 'apply' && observations.every((value, index) => value.state === 'after' && set.files[index].writeAttempted);
const before = observations.every(value => value.state === 'before');
set.status = complete ? 'completed' : before ? direction === 'rollback' ? 'rolled_back' : 'interrupted' : 'partial';
set.requiresVerification = !complete && !before; set.finishedAt = at();
set.summary = complete ? '整批文件的实际建议字节已核对,全部应用完成。' : before
? '全部目标已核对为原字节;这次批次已结束,不会自动重放。' : '批次仍有混合或外部改动,保留实际文件,请核对或回退已写入部分。';
if (!set.requiresVerification) for (const file of set.files) {
const change = session.changes.find(value => value.id === file.changeId);
change.status = complete ? 'applied' : 'rolled_back';
if (complete) change.appliedAt = at(); else { change.rolledBackAt = at(); delete change.appliedAt; }
}
if (!set.requiresVerification) {
session.status = session.changes.some(change => ['pending', 'conflict'].includes(change.status)) ? 'needs_review' : 'completed';
session.recoveryNotice = null;
} else { session.status = 'paused'; session.recoveryNotice = set.summary; }
session.events.push({ id: randomUUID(), kind: 'change_set', label: '多文件变更集 · ' + set.files.length + ' 个文件',
phase: set.status, taskId: set.taskId, runId: set.runId, createdAt: at(), output: set.summary });
this.save(session, set, set.status);
return set;
}
async execute(session, set, snapshots, operation) {
try {
await this.cut('application_started', set);
this.store.invalidateChecks(set.projectId, '多文件批次已进入写入阶段,需要重新检查实际源码。');
for (let index = 0; index < set.files.length; index++) {
operation.controller.signal.throwIfAborted();
set.files[index].writeAttempted = true; set.files[index].state = 'writing';
this.save(session, set, 'write_intent'); await this.cut('write_intent', set, index);
operation.controller.signal.throwIfAborted();
await this.replace(session, set, index, snapshots[index].after, 'apply');
set.files[index].state = 'after'; set.files[index].appliedAt = at();
this.save(session, set, 'file_recorded'); await this.cut('file_recorded', set, index);
}
const result = this.settle(session, set, this.inspect(session, set), 'apply');
await this.cut('finished', set); return result;
} catch (error) {
if (set.status === 'completed') return set;
set.error = error.message; set.status = 'rolling_back'; set.direction = 'rollback'; set.requiresVerification = true;
try {
this.save(session, set, 'rollback_started'); await this.cut('rollback_started', set);
return await this.restore(session, set, this.snapshots(session, set));
} catch (failure) {
set.status = 'unknown'; set.requiresVerification = true; set.summary = '批次中断,实际文件和快照需要核对:' + failure.message;
session.status = 'paused'; session.recoveryNotice = set.summary;
this.save(session, set, 'unknown'); return set;
}
}
}
async restore(session, set, snapshots) {
const project = this.store.project(session.projectId);
for (let index = set.files.length - 1; index >= 0; index--) {
const file = set.files[index], observation = observe(project, file);
if (!file.writeAttempted || observation.state !== 'after') continue;
file.restoreAttempted = true; file.state = 'restoring';
this.save(session, set, 'restore_intent');
await this.cut('restore_intent', set, index);
try { await this.replace(session, set, index, snapshots[index].before, 'rollback'); }
catch (error) { file.restoreError = error.message; continue; }
file.state = 'before'; file.restoredAt = at(); this.save(session, set, 'restore_recorded'); await this.cut('restore_recorded', set, index);
}
const result = this.settle(session, set, this.inspect(session, set), 'rollback');
await this.cut('rollback_finished', set); return result;
}
async reconcile(session, id) {
const set = this.own(session, id);
if (!set.attemptedAt || !['unknown', 'partial', 'completed', 'rolled_back', 'interrupted'].includes(set.status)) throw conflict('这个批次尚未执行或已结束外部改动确认,无需恢复核对。');
this.requireIdle(session, { exceptId: set.id });
this.snapshots(session, set);
return this.settle(session, set, this.inspect(session, set), set.direction === 'rollback' ? 'rollback' : 'apply');
}
async rollback(session, id, fingerprint) {
const set = this.own(session, id, fingerprint, { current: true });
if (typeof fingerprint !== 'string' || !set.attemptedAt || !['completed', 'partial', 'unknown'].includes(set.status)) throw conflict('只有已执行且已审查指纹的批次可以回退。');
this.requireIdle(session, { exceptId: set.id });
const snapshots = this.snapshots(session, set), operation = this.claim(session, set);
try {
set.status = 'rolling_back'; set.direction = 'rollback'; set.requiresVerification = true;
this.save(session, set, 'rollback_started'); this.store.invalidateChecks(set.projectId, '文件批次正在回退,需要重新检查。');
await this.cut('rollback_started', set);
operation.promise = this.restore(session, set, snapshots).finally(() => this.release(set));
operation.promise.catch(() => {});
return await operation.promise;
} catch (error) {
this.release(set); set.status = 'unknown'; set.requiresVerification = true; set.summary = '回退结果需要核对:' + error.message;
this.save(session, set, 'unknown'); throw error;
}
}
acknowledge(session, id, fingerprint, observationFingerprint) {
const set = this.own(session, id, fingerprint, { current: true });
if (typeof fingerprint !== 'string' || set.status !== 'partial' || !set.requiresVerification || typeof observationFingerprint !== 'string') throw conflict('请先核对这个批次的当前文件,再确认保留外部改动。');
this.requireIdle(session, { exceptId: set.id }); this.snapshots(session, set);
const observations = this.inspect(session, set);
if (set.observationFingerprint !== observationFingerprint || observations.some(value => !['before', 'external'].includes(value.state))) throw conflict('当前文件变化或仍有本批次建议内容未回退,请先重新核对/回退。');
set.status = 'resolved_external'; set.requiresVerification = false; set.finishedAt = at();
set.summary = '已明确保留外部改动并结束恢复;本批次未记为成功应用。';
set.files.forEach((file, index) => { const change = session.changes.find(value => value.id === file.changeId);
change.status = observations[index].state === 'external' ? 'external_preserved' : 'rolled_back'; delete change.appliedAt;
});
session.recoveryNotice = null; session.status = session.changes.some(change => ['pending', 'conflict'].includes(change.status)) ? 'needs_review' : 'completed';
this.save(session, set, 'resolved_external'); return set;
}
discard(session, id, fingerprint) {
const set = this.own(session, id, fingerprint, { current: true });
if (typeof fingerprint !== 'string' || !['prepared', 'stale'].includes(set.status) || set.attemptedAt) throw conflict('只有尚未执行的封存批次可以撤销。');
this.requireIdle(session, { exceptId: set.id });
set.status = 'cancelled'; set.finishedAt = at(); set.summary = '已撤销未执行批次,文件提案仍可重新审查。';
for (const file of set.files) { const change = session.changes.find(value => value.id === file.changeId); if (change?.changeSetId === set.id) delete change.changeSetId; }
this.save(session, set, 'cancelled'); return set;
}
async stop(sessionId) {
const operations = [...this.active.values()].filter(value => value.sessionId === sessionId);
for (const operation of operations) operation.controller.abort(new Error('用户停止了文件批次。'));
await Promise.allSettled(operations.map(value => value.promise));
}
async stopAll() { for (const operation of this.active.values()) operation.controller.abort(new Error('宿主正在停止。')); await Promise.allSettled([...this.active.values()].map(value => value.promise)); }
}