godot-daedalus_backend 1.0.0

package/src/tools/tool-idempotency.ts

@@ -0,0 +1,373 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { getToolExecutionLedgerPath } from "../app-paths.js";
+import type { McpHost } from "../mcp/mcp-host.js";
+import { MAX_TOOL_RESULT_CHARS, resolveToolMapping } from "./llm-tools.js";
+import { getToolPolicy } from "./tool-policy.js";
+
+const TOOL_EXECUTION_DEDUP_TTL_MS: number = 30 * 60 * 1000;
+const MAX_COMPLETED_TOOL_EXECUTIONS: number = 500;
+
+type ToolResultContent = {
+	content: Array<{ type: string; text?: string }>;
+};
+
+type ToolExecutionRecord = {
+	fingerprint: string;
+	scope: string;
+	llmToolName: string;
+	serverId: string;
+	toolName: string;
+	argsHash: string;
+	content: string;
+	rawContentLength: number;
+	truncated: boolean;
+	createdAt: string;
+	expiresAt: string;
+};
+
+export type IdempotentToolExecutionResult = {
+	content: string;
+	rawContentLength: number;
+	truncated: boolean;
+	reused: boolean;
+	fingerprint?: string | undefined;
+};
+
+type ToolExecutionIdentity = {
+	fingerprint: string;
+	scope: string;
+	serverId: string;
+	toolName: string;
+	argsHash: string;
+};
+
+const completedToolExecutions: Map<string, ToolExecutionRecord> = new Map();
+const inFlightToolExecutions: Map<string, Promise<IdempotentToolExecutionResult>> = new Map();
+
+let ledgerLoadPromise: Promise<void> | null = null;
+let ledgerWriteQueue: Promise<void> = Promise.resolve();
+
+const GODOT_PROJECT_MUTATION_TOOLS: ReadonlySet<string> = new Set([
+	"mcp_godot_set_project_setting",
+	"mcp_godot_unset_project_setting",
+	"mcp_godot_create_text_file",
+	"mcp_godot_overwrite_text_file",
+	"mcp_godot_replace_text_in_file",
+	"mcp_godot_delete_file",
+	"mcp_godot_create_scene",
+	"mcp_godot_add_node_to_scene",
+	"mcp_godot_attach_script_to_node",
+	"mcp_godot_connect_signal_in_scene",
+	"mcp_godot_apply_scene_patch",
+	"mcp_godot_editor_apply_scene_patch"
+]);
+
+function normalizeForStableJson(value: unknown): unknown {
+	if (Array.isArray(value)) {
+		return value.map((item: unknown): unknown => normalizeForStableJson(item));
+	}
+
+	if (value !== null && typeof value === "object") {
+		const record: Record<string, unknown> = value as Record<string, unknown>;
+		const normalized: Record<string, unknown> = {};
+		for (const key of Object.keys(record).sort()) {
+			normalized[key] = normalizeForStableJson(record[key]);
+		}
+		return normalized;
+	}
+
+	if (value === undefined) {
+		return null;
+	}
+
+	return value;
+}
+
+function stableJson(value: unknown): string {
+	return JSON.stringify(normalizeForStableJson(value));
+}
+
+function sha256(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function trimToolResult(text: string): string {
+	if (text.length <= MAX_TOOL_RESULT_CHARS) {
+		return text;
+	}
+
+	return text.slice(0, MAX_TOOL_RESULT_CHARS) + `\n\n[结果已截断，原始长度 ${text.length} 字符]`;
+}
+
+function extractTextContent(result: ToolResultContent): string {
+	const firstContent = result.content[0];
+	if (firstContent !== undefined && firstContent.text !== undefined) {
+		return firstContent.text;
+	}
+
+	return JSON.stringify(result);
+}
+
+function isRecordExpired(record: ToolExecutionRecord, now: number = Date.now()): boolean {
+	return Date.parse(record.expiresAt) <= now;
+}
+
+function isToolExecutionRecord(value: unknown): value is ToolExecutionRecord {
+	if (value === null || typeof value !== "object") {
+		return false;
+	}
+
+	const record: Partial<ToolExecutionRecord> = value as Partial<ToolExecutionRecord>;
+	return typeof record.fingerprint === "string"
+		&& typeof record.scope === "string"
+		&& typeof record.llmToolName === "string"
+		&& typeof record.serverId === "string"
+		&& typeof record.toolName === "string"
+		&& typeof record.argsHash === "string"
+		&& typeof record.content === "string"
+		&& typeof record.rawContentLength === "number"
+		&& typeof record.truncated === "boolean"
+		&& typeof record.createdAt === "string"
+		&& typeof record.expiresAt === "string";
+}
+
+async function loadLedger(): Promise<void> {
+	try {
+		const raw: string = await readFile(getToolExecutionLedgerPath(), "utf8");
+		const now: number = Date.now();
+		for (const line of raw.split("\n")) {
+			const trimmed: string = line.trim();
+			if (trimmed.length === 0) {
+				continue;
+			}
+
+			try {
+				const parsed: unknown = JSON.parse(trimmed);
+				if (isToolExecutionRecord(parsed) && !isRecordExpired(parsed, now)) {
+					completedToolExecutions.set(parsed.fingerprint, parsed);
+				}
+			} catch {
+				// 忽略损坏的 ledger 行，避免单条记录影响后端启动。
+			}
+		}
+		pruneCompletedToolExecutions(now);
+	} catch {
+		// Ledger 不存在时按空记录处理。
+	}
+}
+
+async function ensureLedgerLoaded(): Promise<void> {
+	if (ledgerLoadPromise === null) {
+		ledgerLoadPromise = loadLedger();
+	}
+
+	await ledgerLoadPromise;
+}
+
+function pruneCompletedToolExecutions(now: number = Date.now()): void {
+	for (const [fingerprint, record] of completedToolExecutions.entries()) {
+		if (isRecordExpired(record, now)) {
+			completedToolExecutions.delete(fingerprint);
+		}
+	}
+
+	while (completedToolExecutions.size > MAX_COMPLETED_TOOL_EXECUTIONS) {
+		const oldestFingerprint: string | undefined = completedToolExecutions.keys().next().value;
+		if (oldestFingerprint === undefined) {
+			break;
+		}
+		completedToolExecutions.delete(oldestFingerprint);
+	}
+}
+
+function enqueueLedgerWrite(record: ToolExecutionRecord): Promise<void> {
+	ledgerWriteQueue = ledgerWriteQueue.then(async (): Promise<void> => {
+		const ledgerPath: string = getToolExecutionLedgerPath();
+		await mkdir(dirname(ledgerPath), { recursive: true });
+		await writeFile(ledgerPath, JSON.stringify(record) + "\n", { encoding: "utf8", flag: "a" });
+	}, async (): Promise<void> => {
+		const ledgerPath: string = getToolExecutionLedgerPath();
+		await mkdir(dirname(ledgerPath), { recursive: true });
+		await writeFile(ledgerPath, JSON.stringify(record) + "\n", { encoding: "utf8", flag: "a" });
+	});
+
+	return ledgerWriteQueue;
+}
+
+export function shouldDedupeLlmToolExecution(llmToolName: string): boolean {
+	const policy = getToolPolicy(llmToolName);
+	return policy?.risk === "write" || policy?.risk === "destructive";
+}
+
+export function getLlmToolExecutionIdentity(
+	llmToolName: string,
+	args: Record<string, unknown>,
+	scope: string = "workspace:none"
+): ToolExecutionIdentity | undefined {
+	if (!shouldDedupeLlmToolExecution(llmToolName)) {
+		return undefined;
+	}
+
+	const mapping = resolveToolMapping(llmToolName);
+	const argsHash: string = sha256(stableJson(args));
+	const fingerprintHash: string = sha256(`${scope}\n${mapping.serverId}\n${mapping.toolName}\n${argsHash}`);
+	return {
+		fingerprint: `${mapping.serverId}:${mapping.toolName}:${fingerprintHash}`,
+		scope,
+		serverId: mapping.serverId,
+		toolName: mapping.toolName,
+		argsHash
+	};
+}
+
+function getMcpExecutionScope(mcpHost: McpHost): string {
+	return mcpHost.getActiveWorkspaceId() ?? "workspace:none";
+}
+
+function addRefreshPath(paths: Set<string>, value: unknown): void {
+	if (typeof value !== "string") {
+		return;
+	}
+
+	const trimmed: string = value.trim();
+	if (trimmed.length === 0) {
+		return;
+	}
+
+	paths.add(trimmed);
+}
+
+function collectGodotRefreshPaths(args: Record<string, unknown>): string[] {
+	const paths: Set<string> = new Set();
+	addRefreshPath(paths, args.relativePath);
+	addRefreshPath(paths, args.scenePath);
+	addRefreshPath(paths, args.scriptPath);
+	addRefreshPath(paths, args.resourcePath);
+	addRefreshPath(paths, args.path);
+
+	const operations: unknown = args.operations;
+	if (Array.isArray(operations)) {
+		for (const operation of operations) {
+			if (operation === null || typeof operation !== "object") {
+				continue;
+			}
+
+			const operationRecord: Record<string, unknown> = operation as Record<string, unknown>;
+			addRefreshPath(paths, operationRecord.scenePath);
+			addRefreshPath(paths, operationRecord.scriptPath);
+			addRefreshPath(paths, operationRecord.resourcePath);
+			addRefreshPath(paths, operationRecord.path);
+		}
+	}
+
+	return [...paths];
+}
+
+function refreshEditorFilesystemAfterGodotMutation(
+	mcpHost: McpHost,
+	llmToolName: string,
+	args: Record<string, unknown>
+): void {
+	if (!GODOT_PROJECT_MUTATION_TOOLS.has(llmToolName)) {
+		return;
+	}
+
+	const changedPaths: string[] = collectGodotRefreshPaths(args);
+	void mcpHost.getEditorBridge().refreshFilesystem(changedPaths).catch((error: unknown): void => {
+		const message: string = error instanceof Error ? error.message : String(error);
+		console.warn(`[godot_editor] resource filesystem refresh failed after ${llmToolName}: ${message}`);
+	});
+}
+
+async function executeMappedTool(
+	mcpHost: McpHost,
+	serverId: string,
+	toolName: string,
+	args: Record<string, unknown>,
+	fingerprint?: string | undefined
+): Promise<IdempotentToolExecutionResult> {
+	const result = await mcpHost.callTool(serverId, toolName, args) as ToolResultContent;
+	const textResult: string = extractTextContent(result);
+	const truncated: boolean = textResult.length > MAX_TOOL_RESULT_CHARS;
+	return {
+		content: trimToolResult(textResult),
+		rawContentLength: textResult.length,
+		truncated,
+		reused: false,
+		fingerprint
+	};
+}
+
+export async function executeLlmToolWithIdempotency(
+	mcpHost: McpHost,
+	llmToolName: string,
+	args: Record<string, unknown>
+): Promise<IdempotentToolExecutionResult> {
+	const identity: ToolExecutionIdentity | undefined = getLlmToolExecutionIdentity(llmToolName, args, getMcpExecutionScope(mcpHost));
+	if (identity === undefined) {
+		const mapping = resolveToolMapping(llmToolName);
+		const result: IdempotentToolExecutionResult = await executeMappedTool(mcpHost, mapping.serverId, mapping.toolName, args);
+		refreshEditorFilesystemAfterGodotMutation(mcpHost, llmToolName, args);
+		return result;
+	}
+
+	await ensureLedgerLoaded();
+	pruneCompletedToolExecutions();
+
+	const existingRecord: ToolExecutionRecord | undefined = completedToolExecutions.get(identity.fingerprint);
+	if (existingRecord !== undefined && !isRecordExpired(existingRecord)) {
+		refreshEditorFilesystemAfterGodotMutation(mcpHost, llmToolName, args);
+		return {
+			content: existingRecord.content,
+			rawContentLength: existingRecord.rawContentLength,
+			truncated: existingRecord.truncated,
+			reused: true,
+			fingerprint: identity.fingerprint
+		};
+	}
+
+	const existingInFlight: Promise<IdempotentToolExecutionResult> | undefined = inFlightToolExecutions.get(identity.fingerprint);
+	if (existingInFlight !== undefined) {
+		const result: IdempotentToolExecutionResult = await existingInFlight;
+		refreshEditorFilesystemAfterGodotMutation(mcpHost, llmToolName, args);
+		return { ...result, reused: true };
+	}
+
+	const executionPromise: Promise<IdempotentToolExecutionResult> = (async (): Promise<IdempotentToolExecutionResult> => {
+		const result: IdempotentToolExecutionResult = await executeMappedTool(
+			mcpHost,
+			identity.serverId,
+			identity.toolName,
+			args,
+			identity.fingerprint
+		);
+		refreshEditorFilesystemAfterGodotMutation(mcpHost, llmToolName, args);
+		const createdAt: string = new Date().toISOString();
+		const record: ToolExecutionRecord = {
+			fingerprint: identity.fingerprint,
+			scope: identity.scope,
+			llmToolName,
+			serverId: identity.serverId,
+			toolName: identity.toolName,
+			argsHash: identity.argsHash,
+			content: result.content,
+			rawContentLength: result.rawContentLength,
+			truncated: result.truncated,
+			createdAt,
+			expiresAt: new Date(Date.now() + TOOL_EXECUTION_DEDUP_TTL_MS).toISOString()
+		};
+		completedToolExecutions.set(identity.fingerprint, record);
+		pruneCompletedToolExecutions();
+		await enqueueLedgerWrite(record);
+		return result;
+	})();
+
+	inFlightToolExecutions.set(identity.fingerprint, executionPromise);
+	try {
+		return await executionPromise;
+	} finally {
+		inFlightToolExecutions.delete(identity.fingerprint);
+	}
+}

package/src/tools/tool-policy-table.ts

@@ -0,0 +1,61 @@
+import type { ToolPolicy } from "./tool-policy.js";
+
+export const TOOL_POLICIES: Record<string, ToolPolicy> = {
+	"mcp_godot_get_project_summary": { risk: "read" },
+	"mcp_godot_list_project_files": { risk: "read" },
+	"mcp_godot_list_scenes": { risk: "read" },
+	"mcp_godot_list_scripts": { risk: "read" },
+	"mcp_godot_read_text_file": { risk: "read" },
+	"mcp_godot_search_text": { risk: "read" },
+	"mcp_godot_get_project_log_config": { risk: "read" },
+	"mcp_godot_list_project_logs": { risk: "read" },
+	"mcp_godot_read_project_log": { risk: "read" },
+	"mcp_godot_get_project_settings": { risk: "read" },
+	"mcp_godot_get_editor_config_summary": { risk: "read" },
+	"mcp_godot_get_editor_settings": { risk: "read" },
+	"mcp_godot_list_editor_config_files": { risk: "read" },
+	"mcp_godot_read_editor_config_file": { risk: "read" },
+	"mcp_godot_get_editor_project_state": { risk: "read" },
+	"mcp_godot_get_recent_projects": { risk: "read" },
+	"mcp_godot_propose_set_project_setting": { risk: "propose" },
+	"mcp_godot_set_project_setting": { risk: "write" },
+	"mcp_godot_propose_unset_project_setting": { risk: "propose" },
+	"mcp_godot_unset_project_setting": { risk: "write" },
+	"mcp_godot_propose_create_text_file": { risk: "propose" },
+	"mcp_godot_create_text_file": { risk: "write" },
+	"mcp_godot_propose_overwrite_text_file": { risk: "propose" },
+	"mcp_godot_overwrite_text_file": { risk: "write" },
+	"mcp_godot_propose_replace_text_in_file": { risk: "propose" },
+	"mcp_godot_replace_text_in_file": { risk: "write" },
+	"mcp_godot_delete_file": { risk: "destructive" },
+	"mcp_godot_inspect_scene_tree": { risk: "read" },
+	"mcp_godot_propose_create_scene": { risk: "propose" },
+	"mcp_godot_create_scene": { risk: "write" },
+	"mcp_godot_propose_add_node_to_scene": { risk: "propose" },
+	"mcp_godot_add_node_to_scene": { risk: "write" },
+	"mcp_godot_propose_attach_script_to_node": { risk: "propose" },
+	"mcp_godot_attach_script_to_node": { risk: "write" },
+	"mcp_godot_propose_connect_signal_in_scene": { risk: "propose" },
+	"mcp_godot_connect_signal_in_scene": { risk: "write" },
+	"mcp_godot_propose_apply_scene_patch": { risk: "propose" },
+	"mcp_godot_apply_scene_patch": { risk: "write" },
+	"mcp_godot_editor_get_context": { risk: "read" },
+	"mcp_godot_editor_get_selected_nodes": { risk: "read" },
+	"mcp_godot_editor_inspect_node": { risk: "read" },
+	"mcp_godot_editor_apply_scene_patch": { risk: "write" },
+	"mcp_godot_lsp_get_status": { risk: "read" },
+	"mcp_godot_lsp_get_file_diagnostics": { risk: "read" },
+	"mcp_godot_lsp_get_document_symbols": { risk: "read" },
+	"mcp_godot_lsp_hover": { risk: "read" },
+	"mcp_godot_lsp_goto_definition": { risk: "read" },
+	"mcp_godot_dap_get_status": { risk: "read" },
+	"mcp_godot_dap_get_last_error": { risk: "read" },
+	"mcp_godot_dap_get_stack_trace": { risk: "read" },
+	"mcp_godot_dap_get_variables": { risk: "read" },
+	"mcp_terminal_get_capabilities": { risk: "read" },
+	"mcp_terminal_run_safe_preset": { risk: "verify" },
+	"mcp_terminal_run_write_preset": { risk: "write" },
+	"mcp_terminal_run_godot_scene_script": { risk: "write" },
+};
+
+export const HARD_BLOCKED_TOOLS: Set<string> = new Set([]);

package/src/tools/tool-policy.ts

@@ -0,0 +1,73 @@
+import { isDynamicMcpToolName } from "./llm-tools.js";
+import { HARD_BLOCKED_TOOLS, TOOL_POLICIES } from "./tool-policy-table.js";
+
+export type ApprovalMode = "read-only" | "manual" | "auto-safe" | "bypass";
+
+export type ToolRisk = "read" | "verify" | "propose" | "write" | "destructive";
+
+export type ToolPolicy = {
+	risk: ToolRisk;
+};
+
+export function getToolPolicy(toolName: string): ToolPolicy | undefined {
+	if (isDynamicMcpToolName(toolName)) {
+		return { risk: "write" };
+	}
+
+	return TOOL_POLICIES[toolName];
+}
+
+export function isHardBlocked(toolName: string): boolean {
+	return HARD_BLOCKED_TOOLS.has(toolName);
+}
+
+export type ApprovalDecision =
+	| { action: "allow" }
+	| { action: "request_approval"; reason: string }
+	| { action: "deny"; reason: string };
+
+export function evaluateToolCall(
+	mode: ApprovalMode,
+	toolName: string,
+	_args: Record<string, unknown>
+): ApprovalDecision {
+	const policy: ToolPolicy | undefined = getToolPolicy(toolName);
+
+	if (!policy) {
+		return { action: "deny", reason: `未知工具: ${toolName}` };
+	}
+
+	if (isHardBlocked(toolName)) {
+		return { action: "deny", reason: "该工具已被硬性禁用" };
+	}
+
+	if (mode === "read-only") {
+		return policy.risk === "read" || policy.risk === "verify"
+			? { action: "allow" }
+			: { action: "deny", reason: "当前为只读模式，不允许写操作" };
+	}
+
+	if (mode === "manual") {
+		if (policy.risk === "read" || policy.risk === "verify" || policy.risk === "propose") {
+			return { action: "allow" };
+		}
+
+		return { action: "request_approval", reason: "写操作需要用户在 Godot 客户端确认" };
+	}
+
+	if (mode === "auto-safe") {
+		if (policy.risk === "read" || policy.risk === "verify" || policy.risk === "propose") {
+			return { action: "allow" };
+		}
+
+		return { action: "request_approval", reason: "此写操作需要确认（auto-safe 模式）" };
+	}
+
+	if (mode === "bypass") {
+		return policy.risk === "destructive"
+			? { action: "request_approval", reason: "破坏性操作仍需用户确认" }
+			: { action: "allow" };
+	}
+
+	return { action: "deny", reason: "未知审批模式" };
+}