godot-daedalus_backend 1.0.1 → 1.0.3

package/README.md

@@ -40,7 +40,7 @@ npm install godot-daedalus_backend
 After installing the package, start it through the published bin command:
 
 ```powershell
-$env:PORT = "8080"
+$env:PORT = "38180"
 godot-daedalus-backend
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "godot-daedalus_backend",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "TypeScript backend for the Godot Daedalus editor assistant plugin.",
   "main": "./src/main.ts",
   "bin": {

package/src/main.ts

@@ -1,7 +1,7 @@
 import { createServer } from "./server/websocket-server.js";
 import { McpHost } from "./mcp/mcp-host.js";
 
-const DEFAULT_PORT: number = 8080;
+const DEFAULT_PORT: number = 38180;
 const portText: string = process.env.PORT ?? String(DEFAULT_PORT);
 const port: number = Number.parseInt(portText, 10);
 

package/src/ping-client.ts

@@ -1,6 +1,6 @@
 import WebSocket from "ws";
 
-const url: string = process.env.WS_URL ?? "ws://localhost:8080";
+const url: string = process.env.WS_URL ?? "ws://localhost:38180";
 const socket: WebSocket = new WebSocket(url);
 
 socket.on("open", (): void => {

package/src/server/backend-health.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const BACKEND_HEALTH_NAME: string = "godot-daedalus-backend";
+const PACKAGE_ROOT: string = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const PACKAGE_JSON_PATH: string = resolve(PACKAGE_ROOT, "package.json");
+
+type PackageManifest = {
+	name?: unknown;
+	version?: unknown;
+};
+
+export type BackendHealthResult = {
+	name: string;
+	version: string;
+	pid: number;
+	mode: "development" | "runtime";
+};
+
+let cachedPackageVersion: string | null = null;
+
+export function getBackendPackageVersion(): string {
+	if (cachedPackageVersion !== null) {
+		return cachedPackageVersion;
+	}
+
+	const envVersion: string | undefined = process.env.npm_package_version;
+	if (envVersion !== undefined && envVersion.trim() !== "") {
+		cachedPackageVersion = envVersion.trim();
+		return cachedPackageVersion;
+	}
+
+	try {
+		const manifestText: string = readFileSync(PACKAGE_JSON_PATH, "utf8");
+		const manifest: PackageManifest = JSON.parse(manifestText) as PackageManifest;
+		if (typeof manifest.version === "string" && manifest.version.trim() !== "") {
+			cachedPackageVersion = manifest.version.trim();
+			return cachedPackageVersion;
+		}
+	} catch {
+		// health 不能因为版本元数据不可读而阻断 WebSocket 启动。
+	}
+
+	cachedPackageVersion = "0.0.0";
+	return cachedPackageVersion;
+}
+
+export function getBackendRuntimeMode(): "development" | "runtime" {
+	if (process.env.NODE_ENV === "development" || process.env.npm_lifecycle_event === "dev") {
+		return "development";
+	}
+
+	return "runtime";
+}
+
+export function createBackendHealthResult(): BackendHealthResult {
+	return {
+		name: BACKEND_HEALTH_NAME,
+		version: getBackendPackageVersion(),
+		pid: process.pid,
+		mode: getBackendRuntimeMode()
+	};
+}

package/src/server/websocket-server.ts

@@ -10,7 +10,7 @@ import {
 	type DeepSeekAgentContinuation,
 	type DeepSeekAgentResult
 } from "../providers/deepseek-agent.js";
-import type { OnToolEvent } from "../tools/tool-dispatcher.js";
+import type { OnToolEvent, ToolEvent } from "../tools/tool-dispatcher.js";
 import { chatWithDeepSeek, createDeepSeekClient, type DeepSeekChatOptions } from "../providers/deepseek-client.js";
 import { McpHost } from "../mcp/mcp-host.js";
 import type { CustomMcpServerRuntimeStatus } from "../mcp/mcp-host.js";
@@ -44,7 +44,7 @@ import {
 	archiveSession, deleteArchivedSession, deleteSession, listArchivedSessions, renameSession, restoreArchivedSession,
 	rewindSessionFromRequest,
 	readSummary, writeSummary,
-	appendSessionEvent, clearSessionEvents,
+	appendSessionEvent, appendApprovalEvent, clearSessionEvents, readApprovalEvents,
 	openSessionRecentTimeline, openSessionTimelinePage,
 	type SessionMetadata,
 	type SessionSummary,
@@ -80,6 +80,18 @@ import {
 	type ThinkingEventBuffer
 } from "./client-session.js";
 import { assertKnownRequestMethod } from "./request-dispatcher.js";
+import { getToolPolicy } from "../tools/tool-policy.js";
+import type { PendingApproval } from "../tools/approval-gateway.js";
+import { getLlmToolExecutionIdentity } from "../tools/tool-idempotency.js";
+import { resolveToolMapping } from "../tools/llm-tools.js";
+import {
+	createPersistedApprovalRequestedData,
+	createRuntimePendingContinuation,
+	foldPendingApprovalStates,
+	serializePendingApprovalState,
+	type PendingApprovalState
+} from "../session/approval-persistence.js";
+import { createBackendHealthResult } from "./backend-health.js";
 
 const tokenCounterPromise: Promise<TokenCounter> = createTokenCounter();
 let sessionCompressorPromptCache: string | undefined;
@@ -98,6 +110,18 @@ const MAX_NEXT_STEP_HINT_COUNT: number = 5;
 const MAX_NEXT_STEP_HINT_MESSAGE_CHARS: number = 320;
 const MAX_GUIDE_TEXT_CHARS: number = 4000;
 
+type WorkflowPhaseToolStats = {
+	toolEvents: number;
+	proposeToolEvents: number;
+	writeToolEvents: number;
+	approvalEvents: number;
+};
+
+type WorkflowPhaseRunResult = {
+	agentResult: DeepSeekAgentResult;
+	toolStats: WorkflowPhaseToolStats;
+};
+
 function fingerprintText(text: string): string {
 	if (text.length === 0) {
 		return "empty";
@@ -1085,6 +1109,73 @@ function createToolEventForwarder(socket: WebSocket, requestId: string, session:
 	};
 }
 
+function createEmptyWorkflowPhaseToolStats(): WorkflowPhaseToolStats {
+	return {
+		toolEvents: 0,
+		proposeToolEvents: 0,
+		writeToolEvents: 0,
+		approvalEvents: 0
+	};
+}
+
+function updateWorkflowPhaseToolStats(stats: WorkflowPhaseToolStats, event: ToolEvent): void {
+	if (!event.type.startsWith("tool.")) {
+		return;
+	}
+
+	stats.toolEvents += 1;
+
+	if (event.type === "tool.approval_required") {
+		stats.approvalEvents += 1;
+	}
+
+	const toolName: string | undefined = "toolName" in event ? event.toolName : undefined;
+	if (toolName === undefined) {
+		return;
+	}
+
+	const policy = getToolPolicy(toolName);
+	if (policy?.risk === "propose") {
+		stats.proposeToolEvents += 1;
+	}
+	if (policy?.risk === "write" || policy?.risk === "destructive") {
+		stats.writeToolEvents += 1;
+	}
+}
+
+function shouldRequireWorkflowWriteTool(phase: WorkflowPhase): boolean {
+	return phase.toolGroup === "write";
+}
+
+function didWorkflowWritePhaseExecute(phase: WorkflowPhase, stats: WorkflowPhaseToolStats): boolean {
+	if (stats.writeToolEvents > 0 || stats.approvalEvents > 0) {
+		return true;
+	}
+
+	return isWorkflowProposalPhase(phase) && stats.proposeToolEvents > 0;
+}
+
+function isWorkflowProposalPhase(phase: WorkflowPhase): boolean {
+	const text: string = `${phase.id}\n${phase.title}\n${phase.instruction}`.toLowerCase();
+	return text.includes("propose")
+		|| text.includes("preview")
+		|| text.includes("diff")
+		|| text.includes("预览")
+		|| text.includes("提案")
+		|| text.includes("方案");
+}
+
+function createWorkflowWriteGuardRetryMessage(phaseMessage: string): string {
+	return [
+		phaseMessage,
+		"",
+		"## 后端执行守卫",
+		"上一次候选回复没有实际调用当前阶段需要的 propose/write 工具，也没有触发审批，因此当前阶段还没有完成。",
+		"如果当前阶段是预览/提案，请调用允许的 propose_* 工具；如果当前阶段是实际修改，请调用写入工具并按审批流程暂停。",
+		"不要只描述计划、步骤或意图。"
+	].join("\n");
+}
+
 function createPendingAiContinuation(
 	params: AiChatParams,
 	options: DeepSeekChatOptions,
@@ -1117,6 +1208,155 @@ function createPendingAiContinuation(
 	return pendingContinuation;
 }
 
+async function persistApprovalRequested(
+	session: ClientSession,
+	mcpHost: McpHost,
+	approvalId: string,
+	pendingContinuation: PendingAiContinuation
+): Promise<void> {
+	if (session.sessionId === undefined) {
+		return;
+	}
+
+	const pendingApproval: PendingApproval | undefined = session.approvalGateway.getPending(approvalId);
+	if (pendingApproval === undefined) {
+		return;
+	}
+
+	await appendApprovalEvent(
+		session.sessionId,
+		approvalId,
+		pendingContinuation.requestId,
+		"requested",
+		createPersistedApprovalRequestedData(pendingApproval, pendingContinuation, mcpHost.getActiveWorkspaceId())
+	);
+}
+
+async function registerPendingApprovalContinuation(
+	session: ClientSession,
+	mcpHost: McpHost,
+	approvalId: string,
+	pendingContinuation: PendingAiContinuation
+): Promise<void> {
+	session.pendingAiContinuations.set(approvalId, pendingContinuation);
+	await persistApprovalRequested(session, mcpHost, approvalId, pendingContinuation);
+}
+
+async function loadHydratedPendingApprovalStates(
+	session: ClientSession,
+	apiKey?: string | undefined
+): Promise<{ states: PendingApprovalState[]; hadEvents: boolean }> {
+	if (session.sessionId === undefined) {
+		return {
+			states: createMemoryPendingApprovalStates(session),
+			hadEvents: false
+		};
+	}
+
+	const approvalEvents = await readApprovalEvents(session.sessionId);
+	if (approvalEvents.length === 0) {
+		return {
+			states: createMemoryPendingApprovalStates(session),
+			hadEvents: false
+		};
+	}
+
+	const states: PendingApprovalState[] = foldPendingApprovalStates(approvalEvents);
+	session.approvalGateway.replacePending(states.map((state: PendingApprovalState): PendingApproval => state.approval));
+	const pendingIds: Set<string> = new Set(states.map((state: PendingApprovalState): string => state.approval.approvalId));
+	for (const approvalId of session.pendingAiContinuations.keys()) {
+		if (!pendingIds.has(approvalId)) {
+			session.pendingAiContinuations.delete(approvalId);
+		}
+	}
+
+	if (apiKey !== undefined) {
+		for (const state of states) {
+			if (state.continuation !== undefined) {
+				session.pendingAiContinuations.set(state.approval.approvalId, createRuntimePendingContinuation(state.continuation, apiKey));
+			}
+		}
+	}
+
+	return {
+		states,
+		hadEvents: true
+	};
+}
+
+function createMemoryPendingApprovalStates(session: ClientSession): PendingApprovalState[] {
+	return session.approvalGateway.listPending().map((pendingApproval: PendingApproval): PendingApprovalState => {
+		const timestamp: string = new Date(pendingApproval.createdAt).toISOString();
+		return {
+			approval: pendingApproval,
+			status: "pending",
+			restored: false,
+			interrupted: false,
+			requestId: "",
+			createdAt: timestamp,
+			updatedAt: timestamp
+		};
+	});
+}
+
+function findPendingApprovalState(states: PendingApprovalState[], approvalId: string): PendingApprovalState | undefined {
+	return states.find((state: PendingApprovalState): boolean => state.approval.approvalId === approvalId);
+}
+
+async function restorePendingContinuationForApproval(
+	session: ClientSession,
+	state: PendingApprovalState | undefined,
+	apiKey: string | undefined
+): Promise<PendingAiContinuation | undefined> {
+	const approvalId: string | undefined = state?.approval.approvalId;
+	if (approvalId !== undefined) {
+		const existingContinuation: PendingAiContinuation | undefined = session.pendingAiContinuations.get(approvalId);
+		if (existingContinuation !== undefined) {
+			return existingContinuation;
+		}
+	}
+
+	if (state?.continuation === undefined || apiKey === undefined) {
+		return undefined;
+	}
+
+	const restoredContinuation: PendingAiContinuation = createRuntimePendingContinuation(state.continuation, apiKey);
+	session.pendingAiContinuations.set(state.approval.approvalId, restoredContinuation);
+	return restoredContinuation;
+}
+
+async function validatePendingApprovalBeforeExecution(
+	session: ClientSession,
+	mcpHost: McpHost,
+	pendingApproval: PendingApproval
+): Promise<string | null> {
+	const decision = await session.approvalGateway.evaluate(pendingApproval.llmToolName, pendingApproval.args, pendingApproval.toolCallId);
+	if (decision.action === "deny") {
+		return decision.reason;
+	}
+
+	try {
+		resolveToolMapping(pendingApproval.llmToolName);
+	} catch (error: unknown) {
+		return error instanceof Error ? error.message : "审批工具当前不可用";
+	}
+
+	const currentIdentity = getLlmToolExecutionIdentity(
+		pendingApproval.llmToolName,
+		pendingApproval.args,
+		mcpHost.getActiveWorkspaceId()
+	);
+	if (
+		pendingApproval.executionFingerprint !== undefined
+		&& currentIdentity !== undefined
+		&& currentIdentity.fingerprint !== pendingApproval.executionFingerprint
+	) {
+		return "当前 workspace 与创建审批时不一致，不能执行该审批。";
+	}
+
+	return null;
+}
+
 function sendAiPaused(socket: WebSocket, requestId: string, agentResult: Extract<DeepSeekAgentResult, { status: "approval_required" }>): void {
 	sendJson(socket, {
 		type: "event",
@@ -1152,7 +1392,7 @@ async function sendContinuedAgentResult(
 			pendingContinuation.stream,
 			pendingContinuation.workflowState
 		);
-		session.pendingAiContinuations.set(agentResult.approvalId, nextPendingContinuation);
+		await registerPendingApprovalContinuation(session, mcpHost, agentResult.approvalId, nextPendingContinuation);
 		sendAiPaused(socket, requestId, agentResult);
 		return;
 	}
@@ -1223,11 +1463,20 @@ async function runWorkflowPhase(
 	persistRequestId: string,
 	streamPhase: boolean,
 	abortSignal?: AbortSignal | undefined
-): Promise<DeepSeekAgentResult> {
-	const onToolEvent: OnToolEvent = createToolEventForwarder(socket, requestId, session, persistRequestId);
-	return streamPhase
+): Promise<WorkflowPhaseRunResult> {
+	const toolStats: WorkflowPhaseToolStats = createEmptyWorkflowPhaseToolStats();
+	const forwardToolEvent: OnToolEvent = createToolEventForwarder(socket, requestId, session, persistRequestId);
+	const onToolEvent: OnToolEvent = (event: ToolEvent): void => {
+		updateWorkflowPhaseToolStats(toolStats, event);
+		forwardToolEvent(event);
+	};
+	const agentResult: DeepSeekAgentResult = streamPhase
 		? await runDeepSeekAgentStreaming(params, options, history, fullSystemPrompt, mcpHost, session.approvalGateway, phase.allowedTools, onToolEvent, abortSignal)
 		: await runDeepSeekAgent(params, options, history, fullSystemPrompt, mcpHost, session.approvalGateway, phase.allowedTools, onToolEvent, abortSignal);
+	return {
+		agentResult,
+		toolStats
+	};
 }
 
 async function createWorkflowPhasePrompt(
@@ -1336,21 +1585,59 @@ async function continueWorkflowExecution(
 		].filter((section: string): boolean => section.length > 0).join("\n\n");
 		const fullSystemPrompt: string = await createWorkflowPhasePrompt(phase, phaseParams, mcpHost, session, requestId, guidePromptSection);
 		let agentResult: DeepSeekAgentResult;
+		let phaseToolStats: WorkflowPhaseToolStats = createEmptyWorkflowPhaseToolStats();
 		try {
-			agentResult = agentResultOverride ?? await runWorkflowPhase(
-				socket,
-				phaseParams,
-				options,
-				state.history,
-				fullSystemPrompt,
-				phase,
-				mcpHost,
-				session,
-				requestId,
-				persistRequestId,
-				streamPhase,
-				abortSignal
-			);
+			if (agentResultOverride !== undefined) {
+				agentResult = agentResultOverride;
+				phaseToolStats.approvalEvents = 1;
+				phaseToolStats.writeToolEvents = 1;
+			} else {
+				let phaseRunResult: WorkflowPhaseRunResult = await runWorkflowPhase(
+					socket,
+					phaseParams,
+					options,
+					state.history,
+					fullSystemPrompt,
+					phase,
+					mcpHost,
+					session,
+					requestId,
+					persistRequestId,
+					streamPhase,
+					abortSignal
+				);
+				agentResult = phaseRunResult.agentResult;
+				phaseToolStats = phaseRunResult.toolStats;
+
+				if (
+					agentResult.status === "completed"
+					&& shouldRequireWorkflowWriteTool(phase)
+					&& !didWorkflowWritePhaseExecute(phase, phaseToolStats)
+				) {
+					const retryPhaseParams: AiChatParams = createPhaseParams(
+						state.originalParams,
+						phase,
+						createWorkflowWriteGuardRetryMessage(phaseMessage),
+						false
+					);
+					phaseRunResult = await runWorkflowPhase(
+						socket,
+						retryPhaseParams,
+						options,
+						state.history,
+						fullSystemPrompt,
+						phase,
+						mcpHost,
+						session,
+						requestId,
+						persistRequestId,
+						false,
+						abortSignal
+					);
+					agentResult = phaseRunResult.agentResult;
+					phaseToolStats = phaseRunResult.toolStats;
+				}
+			}
 		} catch (error: unknown) {
 			throw new WorkflowExecutionError(error instanceof Error ? error.message : "Workflow phase failed", plan, error);
 		}
@@ -1359,7 +1646,7 @@ async function continueWorkflowExecution(
 		if (agentResult.status === "approval_required") {
 			plan = updateWorkflowPhaseStatus(plan, phase.id, "paused");
 			const pausedState: WorkflowRunState = { ...state, plan, phaseIndex: index, phaseOutputs };
-			session.pendingAiContinuations.set(agentResult.approvalId, createWorkflowPendingContinuation(
+			const pendingContinuation: PendingAiContinuation = createWorkflowPendingContinuation(
 				phaseParams,
 				options,
 				agentResult,
@@ -1368,12 +1655,22 @@ async function continueWorkflowExecution(
 				persistRequestId,
 				userCreatedAt,
 				streamPhase
-			));
+			);
+			await registerPendingApprovalContinuation(session, mcpHost, agentResult.approvalId, pendingContinuation);
 			sendWorkflowTodoSnapshot(socket, requestId, session, plan, persistRequestId);
 			sendAiPaused(socket, requestId, agentResult);
 			return;
 		}
 
+		if (shouldRequireWorkflowWriteTool(phase) && !didWorkflowWritePhaseExecute(phase, phaseToolStats)) {
+			const guardMessage: string = `写入阶段「${phase.title}」没有实际调用写入工具或触发审批，已阻止将该 Todo 标记为完成。`;
+			throw new WorkflowExecutionError(
+				guardMessage,
+				plan,
+				new Error(guardMessage)
+			);
+		}
+
 		phaseOutputs = appendPhaseOutput(phaseOutputs, phase, agentResult.text);
 		plan = updateWorkflowPhaseStatus(plan, phase.id, "done");
 		state = { ...state, plan, phaseIndex: index + 1, phaseOutputs };
@@ -1996,12 +2293,7 @@ async function handleRequest(socket: WebSocket, request: ClientRequest, session:
 				type: "response",
 				id: request.id,
 				ok: true,
-				result: {
-					name: "godot-daedalus-backend",
-					version: "1.0.1",
-					pid: process.pid,
-					mode: process.env.NODE_ENV === "development" || process.env.npm_lifecycle_event === "dev" ? "development" : "runtime"
-				}
+				result: createBackendHealthResult()
 			});
 			break;
 
@@ -2273,7 +2565,7 @@ async function handleRequest(socket: WebSocket, request: ClientRequest, session:
 					const agentResult: DeepSeekAgentResult = await runDeepSeekAgentStreaming(params, options, history, fullSystemPrompt, mcpHost, session.approvalGateway, allowedToolNames, onToolEvent, abortController.signal);
 
 					if (agentResult.status === "approval_required") {
-						session.pendingAiContinuations.set(agentResult.approvalId, createPendingAiContinuation(
+						const pendingContinuation: PendingAiContinuation = createPendingAiContinuation(
 							params,
 							options,
 							agentResult.continuation,
@@ -2282,7 +2574,8 @@ async function handleRequest(socket: WebSocket, request: ClientRequest, session:
 							request.id,
 							turnStartedAt,
 							true
-						));
+						);
+						await registerPendingApprovalContinuation(session, mcpHost, agentResult.approvalId, pendingContinuation);
 						sendAiPaused(socket, request.id, agentResult);
 						break;
 					}
@@ -2308,7 +2601,7 @@ async function handleRequest(socket: WebSocket, request: ClientRequest, session:
 					const agentResult: DeepSeekAgentResult = await runDeepSeekAgent(params, options, history, fullSystemPrompt, mcpHost, session.approvalGateway, allowedToolNames, onToolEvent, abortController.signal);
 
 					if (agentResult.status === "approval_required") {
-						session.pendingAiContinuations.set(agentResult.approvalId, createPendingAiContinuation(
+						const pendingContinuation: PendingAiContinuation = createPendingAiContinuation(
 							params,
 							options,
 							agentResult.continuation,
@@ -2317,7 +2610,8 @@ async function handleRequest(socket: WebSocket, request: ClientRequest, session:
 							request.id,
 							turnStartedAt,
 							false
-						));
+						);
+						await registerPendingApprovalContinuation(session, mcpHost, agentResult.approvalId, pendingContinuation);
 						sendJson(socket, {
 							type: "response",
 							id: request.id,
@@ -2509,6 +2803,7 @@ async function handleRequest(socket: WebSocket, request: ClientRequest, session:
 
 		case "session.info":
 			await waitForFullSessionLoad(session);
+			await loadHydratedPendingApprovalStates(session);
 			sendJson(socket, {
 				type: "response",
 				id: request.id,
@@ -3570,16 +3865,19 @@ async function handleRequest(socket: WebSocket, request: ClientRequest, session:
 		}
 
 		case "approval.list":
+		{
+			const hydrated = await loadHydratedPendingApprovalStates(session);
 			sendJson(socket, {
 				type: "response",
 				id: request.id,
 				ok: true,
 				result: {
-					pending: session.approvalGateway.listPending(),
+					pending: hydrated.states.map(serializePendingApprovalState),
 					mode: session.approvalGateway.getMode()
 				}
 			});
 			break;
+		}
 
 		case "approval.mode.set":
 			session.approvalGateway.setMode(request.params.mode);
@@ -3598,6 +3896,8 @@ async function handleRequest(socket: WebSocket, request: ClientRequest, session:
 			const abortController: AbortController = new AbortController();
 			session.activeAbortControllers.set(request.id, abortController);
 			try {
+				const apiKey: string | undefined = await ensureProviderConfigured(session);
+				const hydrated = await loadHydratedPendingApprovalStates(session, apiKey);
 				const pending = session.approvalGateway.getPending(request.params.approvalId);
 				if (!pending) {
 					sendJson(socket, {
@@ -3609,8 +3909,54 @@ async function handleRequest(socket: WebSocket, request: ClientRequest, session:
 					break;
 				}
 
-				const pendingContinuation: PendingAiContinuation | undefined = session.pendingAiContinuations.get(request.params.approvalId);
+				const validationError: string | null = await validatePendingApprovalBeforeExecution(session, mcpHost, pending);
+				if (validationError !== null) {
+					if (session.sessionId !== undefined) {
+						await appendApprovalEvent(session.sessionId, pending.approvalId, findPendingApprovalState(hydrated.states, pending.approvalId)?.requestId ?? request.id, "failed", {
+							message: validationError
+						});
+					}
+					sendJson(socket, {
+						type: "response",
+						id: request.id,
+						ok: false,
+						error: { code: "approval_validation_failed", message: validationError }
+					});
+					break;
+				}
+
+				const pendingState: PendingApprovalState | undefined = findPendingApprovalState(hydrated.states, request.params.approvalId);
+				const pendingContinuation: PendingAiContinuation | undefined = await restorePendingContinuationForApproval(session, pendingState, apiKey);
+				if (pendingState?.continuation !== undefined && pendingContinuation === undefined) {
+					const message: string = "当前没有可用的 DeepSeek API key，无法恢复审批后的 LLM continuation。请先配置 provider 后重试。";
+					if (session.sessionId !== undefined) {
+						await appendApprovalEvent(session.sessionId, pending.approvalId, pendingState.requestId, "failed", { message });
+					}
+					sendJson(socket, {
+						type: "response",
+						id: request.id,
+						ok: false,
+						error: { code: "provider_not_configured", message }
+					});
+					break;
+				}
+				const approvalPersistRequestId: string = pendingContinuation?.requestId ?? pendingState?.requestId ?? request.id;
+				if (session.sessionId !== undefined) {
+					await appendApprovalEvent(session.sessionId, pending.approvalId, approvalPersistRequestId, "approved", {
+						approvedAt: new Date().toISOString()
+					});
+					await appendApprovalEvent(session.sessionId, pending.approvalId, approvalPersistRequestId, "executing", {
+						startedAt: new Date().toISOString()
+					});
+				}
 				const result = await session.approvalGateway.approve(request.params.approvalId, mcpHost);
+				if (session.sessionId !== undefined) {
+					await appendApprovalEvent(session.sessionId, pending.approvalId, approvalPersistRequestId, "executed", {
+						resultChars: result.content.length,
+						cached: result.cached === true,
+						executedAt: new Date().toISOString()
+					});
+				}
 
 				sendJson(socket, {
 					type: "response",
@@ -3707,6 +4053,11 @@ async function handleRequest(socket: WebSocket, request: ClientRequest, session:
 					sendAiCancelled(socket, request.id);
 					break;
 				}
+				if (session.sessionId !== undefined) {
+					await appendApprovalEvent(session.sessionId, request.params.approvalId, request.id, "failed", {
+						message: error instanceof Error ? error.message : "Approval failed"
+					});
+				}
 				sendJson(socket, {
 					type: "response",
 					id: request.id,
@@ -3724,7 +4075,15 @@ async function handleRequest(socket: WebSocket, request: ClientRequest, session:
 
 		case "approval.reject": {
 			try {
+				const hydrated = await loadHydratedPendingApprovalStates(session);
+				const pendingState: PendingApprovalState | undefined = findPendingApprovalState(hydrated.states, request.params.approvalId);
 				const rejected = session.approvalGateway.reject(request.params.approvalId);
+				session.pendingAiContinuations.delete(request.params.approvalId);
+				if (session.sessionId !== undefined) {
+					await appendApprovalEvent(session.sessionId, request.params.approvalId, pendingState?.requestId ?? request.id, "rejected", {
+						rejectedAt: new Date().toISOString()
+					});
+				}
 				sendJson(socket, {
 					type: "response",
 					id: request.id,

package/src/session/approval-persistence.ts

@@ -0,0 +1,279 @@
+import type { AiChatParams } from "../protocol/types.js";
+import type { DeepSeekAgentContinuation } from "../providers/deepseek-agent.js";
+import type { DeepSeekChatOptions } from "../providers/deepseek-client.js";
+import type { PendingAiContinuation } from "../server/client-session.js";
+import type { PendingApproval } from "../tools/approval-gateway.js";
+import type { WorkflowRunState } from "../workflow/types.js";
+import type { StoredApprovalEvent } from "./session-store.js";
+
+export type PersistedDeepSeekChatOptions = {
+	model?: string | undefined;
+	baseUrl?: string | undefined;
+};
+
+export type PersistedPendingAiContinuation = {
+	params: AiChatParams;
+	options: PersistedDeepSeekChatOptions;
+	continuation: DeepSeekAgentContinuation;
+	allowedToolNames?: readonly string[] | undefined;
+	userMessage: string;
+	requestId: string;
+	userCreatedAt: string;
+	stream: boolean;
+	workflowState?: WorkflowRunState | undefined;
+};
+
+export type PersistedApprovalRequestedData = {
+	approval: PendingApproval;
+	continuation?: PersistedPendingAiContinuation | undefined;
+	workspaceId?: string | undefined;
+	createdAt: string;
+};
+
+export type PendingApprovalState = {
+	approval: PendingApproval;
+	status: "pending" | "interrupted";
+	restored: boolean;
+	interrupted: boolean;
+	requestId: string;
+	createdAt: string;
+	updatedAt: string;
+	continuation?: PersistedPendingAiContinuation | undefined;
+	workspaceId?: string | undefined;
+	lastError?: string | undefined;
+};
+
+export function createPersistedApprovalRequestedData(
+	approval: PendingApproval,
+	continuation: PendingAiContinuation | undefined,
+	workspaceId: string | undefined
+): PersistedApprovalRequestedData {
+	const data: PersistedApprovalRequestedData = {
+		approval,
+		createdAt: new Date(approval.createdAt).toISOString()
+	};
+
+	if (continuation !== undefined) {
+		data.continuation = createPersistedPendingContinuation(continuation);
+	}
+	if (workspaceId !== undefined) {
+		data.workspaceId = workspaceId;
+	}
+
+	return data;
+}
+
+export function createRuntimePendingContinuation(
+	persisted: PersistedPendingAiContinuation,
+	apiKey: string
+): PendingAiContinuation {
+	const options: DeepSeekChatOptions = { apiKey };
+	if (persisted.options.model !== undefined) {
+		options.model = persisted.options.model;
+	}
+	if (persisted.options.baseUrl !== undefined) {
+		options.baseUrl = persisted.options.baseUrl;
+	}
+
+	const continuation: PendingAiContinuation = {
+		params: persisted.params,
+		options,
+		continuation: persisted.continuation,
+		userMessage: persisted.userMessage,
+		requestId: persisted.requestId,
+		userCreatedAt: persisted.userCreatedAt,
+		stream: persisted.stream
+	};
+
+	if (persisted.allowedToolNames !== undefined) {
+		continuation.allowedToolNames = [...persisted.allowedToolNames];
+	}
+	if (persisted.workflowState !== undefined) {
+		continuation.workflowState = persisted.workflowState;
+	}
+
+	return continuation;
+}
+
+export function foldPendingApprovalStates(events: StoredApprovalEvent[]): PendingApprovalState[] {
+	const states: Map<string, PendingApprovalState> = new Map();
+	const sortedEvents: StoredApprovalEvent[] = [...events].sort((left: StoredApprovalEvent, right: StoredApprovalEvent): number => {
+		const timeComparison: number = left.createdAt.localeCompare(right.createdAt);
+		return timeComparison !== 0 ? timeComparison : left.id.localeCompare(right.id);
+	});
+
+	for (const event of sortedEvents) {
+		if (event.schemaVersion !== 1) {
+			continue;
+		}
+
+		if (event.event === "requested") {
+			const requestedData: PersistedApprovalRequestedData | null = parseRequestedData(event.data);
+			if (requestedData === null) {
+				continue;
+			}
+
+			states.set(event.approvalId, {
+				approval: requestedData.approval,
+				status: "pending",
+				restored: true,
+				interrupted: false,
+				requestId: event.requestId,
+				createdAt: event.createdAt,
+				updatedAt: event.createdAt,
+				continuation: requestedData.continuation,
+				workspaceId: requestedData.workspaceId
+			});
+			continue;
+		}
+
+		const existing: PendingApprovalState | undefined = states.get(event.approvalId);
+		if (existing === undefined) {
+			continue;
+		}
+
+		if (event.event === "rejected" || event.event === "executed" || event.event === "cancelled") {
+			states.delete(event.approvalId);
+			continue;
+		}
+
+		if (event.event === "executing") {
+			existing.status = "interrupted";
+			existing.interrupted = true;
+			existing.updatedAt = event.createdAt;
+			states.set(event.approvalId, existing);
+			continue;
+		}
+
+		if (event.event === "approved") {
+			existing.updatedAt = event.createdAt;
+			states.set(event.approvalId, existing);
+			continue;
+		}
+
+		if (event.event === "failed") {
+			existing.status = "pending";
+			existing.interrupted = false;
+			existing.updatedAt = event.createdAt;
+			existing.lastError = extractErrorMessage(event.data);
+			states.set(event.approvalId, existing);
+		}
+	}
+
+	return [...states.values()];
+}
+
+export function serializePendingApprovalState(state: PendingApprovalState): Record<string, unknown> {
+	const result: Record<string, unknown> = {
+		...state.approval,
+		status: state.status,
+		restored: state.restored,
+		interrupted: state.interrupted,
+		requestId: state.requestId,
+		createdAt: state.createdAt,
+		updatedAt: state.updatedAt
+	};
+
+	if (state.lastError !== undefined) {
+		result.lastError = state.lastError;
+	}
+	if (state.workspaceId !== undefined) {
+		result.workspaceId = state.workspaceId;
+	}
+
+	return result;
+}
+
+function createPersistedPendingContinuation(continuation: PendingAiContinuation): PersistedPendingAiContinuation {
+	const options: PersistedDeepSeekChatOptions = {};
+	if (continuation.options.model !== undefined) {
+		options.model = continuation.options.model;
+	}
+	if (continuation.options.baseUrl !== undefined) {
+		options.baseUrl = continuation.options.baseUrl;
+	}
+
+	const persisted: PersistedPendingAiContinuation = {
+		params: continuation.params,
+		options,
+		continuation: continuation.continuation,
+		userMessage: continuation.userMessage,
+		requestId: continuation.requestId,
+		userCreatedAt: continuation.userCreatedAt,
+		stream: continuation.stream
+	};
+
+	if (continuation.allowedToolNames !== undefined) {
+		persisted.allowedToolNames = [...continuation.allowedToolNames];
+	}
+	if (continuation.workflowState !== undefined) {
+		persisted.workflowState = continuation.workflowState;
+	}
+
+	return persisted;
+}
+
+function parseRequestedData(value: unknown): PersistedApprovalRequestedData | null {
+	if (!isRecord(value)) {
+		return null;
+	}
+
+	const approvalValue: unknown = value.approval;
+	if (!isPendingApproval(approvalValue)) {
+		return null;
+	}
+
+	const data: PersistedApprovalRequestedData = {
+		approval: approvalValue,
+		createdAt: typeof value.createdAt === "string" ? value.createdAt : new Date(approvalValue.createdAt).toISOString()
+	};
+
+	if (isPersistedContinuation(value.continuation)) {
+		data.continuation = value.continuation;
+	}
+	if (typeof value.workspaceId === "string") {
+		data.workspaceId = value.workspaceId;
+	}
+
+	return data;
+}
+
+function isPersistedContinuation(value: unknown): value is PersistedPendingAiContinuation {
+	if (!isRecord(value)) {
+		return false;
+	}
+
+	return isRecord(value.params)
+		&& isRecord(value.options)
+		&& isRecord(value.continuation)
+		&& typeof value.userMessage === "string"
+		&& typeof value.requestId === "string"
+		&& typeof value.userCreatedAt === "string"
+		&& typeof value.stream === "boolean";
+}
+
+function isPendingApproval(value: unknown): value is PendingApproval {
+	if (!isRecord(value)) {
+		return false;
+	}
+
+	return typeof value.approvalId === "string"
+		&& typeof value.toolCallId === "string"
+		&& typeof value.toolName === "string"
+		&& typeof value.llmToolName === "string"
+		&& isRecord(value.args)
+		&& typeof value.reason === "string"
+		&& typeof value.createdAt === "number";
+}
+
+function extractErrorMessage(value: unknown): string | undefined {
+	if (!isRecord(value)) {
+		return undefined;
+	}
+
+	return typeof value.message === "string" ? value.message : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/session/session-store.ts

@@ -36,6 +36,16 @@ export type StoredSessionEvent = {
 	createdAt: string;
 };
 
+export type StoredApprovalEvent = {
+	id: string;
+	schemaVersion: 1;
+	approvalId: string;
+	requestId: string;
+	event: string;
+	data: unknown;
+	createdAt: string;
+};
+
 export type StoredSession = {
 	metadata: SessionMetadata;
 	messages: StoredMessage[];
@@ -68,7 +78,7 @@ function assertSafeSessionId(sessionId: string): string {
 	return sessionId;
 }
 
-function getSessionDir(sessionId: string): string {
+export function getSessionDir(sessionId: string): string {
 	return join(SESSIONS_DIR, assertSafeSessionId(sessionId));
 }
 
@@ -119,6 +129,10 @@ function eventsPath(sessionId: string): string {
 	return join(getSessionDir(sessionId), "events.jsonl");
 }
 
+function approvalEventsPath(sessionId: string): string {
+	return join(getSessionDir(sessionId), "approval-events.jsonl");
+}
+
 export async function createSession(title: string, workspaceId?: string, skillId?: string): Promise<SessionMetadata> {
 	const timestamp: string = new Date().toISOString();
 	const dateStr: string = timestamp.slice(0, 10).replace(/-/g, "");
@@ -137,6 +151,7 @@ export async function createSession(title: string, workspaceId?: string, skillId
 	await writeFile(join(dir, "metadata.json"), JSON.stringify(metadata, null, 2), "utf8");
 	await writeFile(join(dir, "messages.jsonl"), "", "utf8");
 	await writeFile(join(dir, "events.jsonl"), "", "utf8");
+	await writeFile(join(dir, "approval-events.jsonl"), "", "utf8");
 
 	return metadata;
 }
@@ -451,6 +466,18 @@ export async function rewindSessionFromRequest(sessionId: string, requestId: str
 		keptEvents.map((event: StoredSessionEvent): string => JSON.stringify(event) + "\n").join(""),
 		"utf8"
 	);
+	try {
+		const rawApprovalEvents: string = await readFile(approvalEventsPath(sessionId), "utf8");
+		const keptApprovalEvents: StoredApprovalEvent[] = parseJsonLines<StoredApprovalEvent>(rawApprovalEvents)
+			.filter((event: StoredApprovalEvent): boolean => !removedRequestIds.has(event.requestId));
+		await writeFile(
+			approvalEventsPath(sessionId),
+			keptApprovalEvents.map((event: StoredApprovalEvent): string => JSON.stringify(event) + "\n").join(""),
+			"utf8"
+		);
+	} catch {
+		// Older sessions may not have approval persistence yet.
+	}
 
 	return keptMessages;
 }
@@ -477,6 +504,33 @@ export async function appendSessionEvent(sessionId: string, requestId: string, e
 	await writeFile(eventFile, line, { encoding: "utf8", flag: "a" });
 }
 
+export async function appendApprovalEvent(sessionId: string, approvalId: string, requestId: string, event: string, data: unknown): Promise<void> {
+	await ensureSessionsDir();
+	const eventFile: string = approvalEventsPath(sessionId);
+	const timestamp: string = new Date().toISOString();
+	const record: StoredApprovalEvent = {
+		id: `approval-event-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+		schemaVersion: 1,
+		approvalId,
+		requestId,
+		event,
+		data,
+		createdAt: timestamp
+	};
+	const line: string = JSON.stringify(record) + "\n";
+	await writeFile(eventFile, line, { encoding: "utf8", flag: "a" });
+}
+
+export async function readApprovalEvents(sessionId: string): Promise<StoredApprovalEvent[]> {
+	await ensureSessionsDir();
+	try {
+		const rawLines: string = await readFile(approvalEventsPath(sessionId), "utf8");
+		return parseJsonLines<StoredApprovalEvent>(rawLines);
+	} catch {
+		return [];
+	}
+}
+
 export async function clearSessionEvents(sessionId: string): Promise<void> {
 	await ensureSessionsDir();
 	await writeFile(eventsPath(sessionId), "", "utf8");

package/src/skills/registry.ts

@@ -56,6 +56,7 @@ const READ_TOOLS: string[] = [
 ];
 
 const FILE_CREATE_TOOLS: string[] = [
+	"mcp_godot_propose_create_text_file",
 	"mcp_godot_create_text_file"
 ];
 
@@ -71,7 +72,9 @@ const TERMINAL_WRITE_TOOLS: string[] = [
 ];
 
 const FILE_EDIT_TOOLS: string[] = [
+	"mcp_godot_propose_overwrite_text_file",
 	"mcp_godot_overwrite_text_file",
+	"mcp_godot_propose_replace_text_in_file",
 	"mcp_godot_replace_text_in_file",
 	"mcp_godot_propose_set_project_setting",
 	"mcp_godot_set_project_setting",
@@ -80,10 +83,15 @@ const FILE_EDIT_TOOLS: string[] = [
 ];
 
 const SCENE_WRITE_TOOLS: string[] = [
+	"mcp_godot_propose_create_scene",
 	"mcp_godot_create_scene",
+	"mcp_godot_propose_add_node_to_scene",
 	"mcp_godot_add_node_to_scene",
+	"mcp_godot_propose_attach_script_to_node",
 	"mcp_godot_attach_script_to_node",
+	"mcp_godot_propose_connect_signal_in_scene",
 	"mcp_godot_connect_signal_in_scene",
+	"mcp_godot_propose_apply_scene_patch",
 	"mcp_godot_apply_scene_patch",
 	"mcp_godot_editor_apply_scene_patch"
 ];

package/src/tools/approval-gateway.ts

@@ -20,7 +20,6 @@ export type ApprovalResult =
 
 export class ApprovalGateway {
 	private pendingApprovals: Map<string, PendingApproval> = new Map();
-	private approvalIdCounter: number = 0;
 	private mode: ApprovalMode;
 
 	constructor(mode: ApprovalMode = "manual") {
@@ -43,6 +42,26 @@ export class ApprovalGateway {
 		return this.pendingApprovals.get(approvalId);
 	}
 
+	replacePending(pendingApprovals: PendingApproval[]): void {
+		this.pendingApprovals.clear();
+		for (const pendingApproval of pendingApprovals) {
+			this.pendingApprovals.set(pendingApproval.approvalId, pendingApproval);
+		}
+	}
+
+	upsertPending(pendingApproval: PendingApproval): void {
+		this.pendingApprovals.set(pendingApproval.approvalId, pendingApproval);
+	}
+
+	removePending(approvalId: string): PendingApproval | undefined {
+		const pending: PendingApproval | undefined = this.pendingApprovals.get(approvalId);
+		if (pending !== undefined) {
+			this.pendingApprovals.delete(approvalId);
+		}
+
+		return pending;
+	}
+
 	async evaluate(
 		llmToolName: string,
 		args: Record<string, unknown>,
@@ -67,8 +86,7 @@ export class ApprovalGateway {
 			}
 		}
 
-		const approvalId: string = `approval-${this.approvalIdCounter}`;
-		this.approvalIdCounter += 1;
+		const approvalId: string = `approval-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
 
 		const pending: PendingApproval = {
 			approvalId,
@@ -92,9 +110,8 @@ export class ApprovalGateway {
 			throw new Error(`Approval not found: ${approvalId}`);
 		}
 
-		this.pendingApprovals.delete(approvalId);
-
 		const result = await executeLlmToolWithIdempotency(mcpHost, pending.llmToolName, pending.args);
+		this.pendingApprovals.delete(approvalId);
 		return { content: result.content, cached: result.reused };
 	}
 

package/src/workflow/planner.ts

@@ -44,13 +44,21 @@ export const VERIFY_TOOLS: string[] = [
 ];
 
 export const WRITE_TOOLS: string[] = [
+	"mcp_godot_propose_create_text_file",
 	"mcp_godot_create_text_file",
+	"mcp_godot_propose_overwrite_text_file",
 	"mcp_godot_overwrite_text_file",
+	"mcp_godot_propose_replace_text_in_file",
 	"mcp_godot_replace_text_in_file",
+	"mcp_godot_propose_create_scene",
 	"mcp_godot_create_scene",
+	"mcp_godot_propose_add_node_to_scene",
 	"mcp_godot_add_node_to_scene",
+	"mcp_godot_propose_attach_script_to_node",
 	"mcp_godot_attach_script_to_node",
+	"mcp_godot_propose_connect_signal_in_scene",
 	"mcp_godot_connect_signal_in_scene",
+	"mcp_godot_propose_apply_scene_patch",
 	"mcp_godot_apply_scene_patch",
 	"mcp_godot_editor_apply_scene_patch",
 	"mcp_godot_propose_set_project_setting",

package/src/workflow/runner.ts

@@ -86,12 +86,14 @@ export function createPhaseParams(originalParams: AiChatParams, phase: WorkflowP
 }
 
 export function createPhasePrompt(phase: WorkflowPhase, skillPrompt: string, mcpSystemContext: string): string {
+	const toolGroupRules: string[] = createPhaseToolGroupRules(phase);
 	return [
 		"## 工作流阶段约束",
 		`- 当前阶段：${phase.title}（${phase.id}）`,
 		`- 阶段目标：${phase.instruction}`,
 		"- 只完成当前阶段，不要提前总结整个任务。",
 		"- 如果需要写入或执行审批工具，按现有审批流程暂停。",
+		...toolGroupRules,
 		"- 当前阶段实际可用工具：",
 		...phase.allowedTools.map((toolName: string): string => `  - ${toolName}`),
 		"",
@@ -100,6 +102,24 @@ export function createPhasePrompt(phase: WorkflowPhase, skillPrompt: string, mcp
 	].filter((part: string): boolean => part.length > 0).join("\n\n");
 }
 
+function createPhaseToolGroupRules(phase: WorkflowPhase): string[] {
+	if (phase.toolGroup === "write") {
+		return [
+			"- 当前是写入/提案阶段：如果阶段目标是预览、提案或 diff，必须调用对应 propose_* 工具。",
+			"- 如果阶段目标是实际创建、修改、删除或应用补丁，必须调用实际写入工具；写入工具触发审批时按现有流程暂停。",
+			"- 不要只输出计划、意图或“稍后将执行”；后端会把未调用当前阶段所需工具的阶段视为未完成。"
+		];
+	}
+
+	if (phase.toolGroup === "verify") {
+		return [
+			"- 当前是验证阶段：优先实际调用诊断或验证工具，不要只描述验证计划。"
+		];
+	}
+
+	return [];
+}
+
 export function appendPhaseOutput(outputs: WorkflowPhaseOutput[], phase: WorkflowPhase, text: string): WorkflowPhaseOutput[] {
 	const clippedText: string = text.length > MAX_PHASE_OUTPUT_CHARS
 		? `${text.slice(0, MAX_PHASE_OUTPUT_CHARS)}\n\n[阶段输出已截断，原始长度 ${text.length} 字符]`