godot-daedalus_backend 1.0.0

package/src/mcp/tscn-tools.ts

@@ -0,0 +1,302 @@
+export type TscnSection = {
+	type: string;
+	attributes: Record<string, string>;
+	lineIndex: number;
+};
+
+export type TscnNode = {
+	name: string;
+	type: string;
+	parent: string | null;
+	instance: string | null;
+	script: string | null;
+	properties: Record<string, string>;
+	lineStart: number;
+	lineEnd: number;
+};
+
+export type TscnConnection = {
+	signal: string;
+	from: string;
+	to: string;
+	method: string;
+	flags?: string | undefined;
+	binds?: string | undefined;
+	lineIndex: number;
+};
+
+export type TscnData = {
+	header: TscnSection | null;
+	nodes: TscnNode[];
+	connections: TscnConnection[];
+};
+
+export type ScenePatchOperation =
+	| { type: "add_node"; parentPath: string; nodeType: string; nodeName: string; properties?: Record<string, string> | undefined }
+	| { type: "attach_script"; nodePath: string; scriptPath: string }
+	| { type: "connect_signal"; signal: string; fromNode: string; toNode: string; method: string; flags?: number | undefined; binds?: string | undefined };
+
+export function parseSectionHeader(line: string, lineIndex: number = 0): TscnSection | null {
+	const match: RegExpMatchArray | null = line.match(/^\[([a-zA-Z_][a-zA-Z0-9_]*)\s*(.*)\]$/);
+	if (match === null) {
+		return null;
+	}
+
+	const attributes: Record<string, string> = {};
+	const rest: string = match[2] ?? "";
+	for (const attrMatch of rest.matchAll(/([a-zA-Z_][a-zA-Z0-9_]*)=("[^"]*"|[^\s]+)/g)) {
+		attributes[attrMatch[1] as string] = attrMatch[2] as string;
+	}
+
+	return {
+		type: match[1] as string,
+		attributes,
+		lineIndex
+	};
+}
+
+function unquoteTscnString(value: string | undefined): string {
+	if (value === undefined) {
+		return "";
+	}
+	if (value.startsWith("\"") && value.endsWith("\"")) {
+		return value.slice(1, -1);
+	}
+	return value;
+}
+
+export function quoteTscnString(value: string): string {
+	return value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"");
+}
+
+export function parseTscn(content: string): TscnData {
+	const lines: string[] = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+	const data: TscnData = {
+		header: null,
+		nodes: [],
+		connections: []
+	};
+	let currentNode: TscnNode | null = null;
+
+	function finishNode(endLine: number): void {
+		if (currentNode !== null) {
+			currentNode.lineEnd = endLine;
+			data.nodes.push(currentNode);
+			currentNode = null;
+		}
+	}
+
+	for (let index = 0; index < lines.length; index += 1) {
+		const line: string = lines[index] ?? "";
+		const section: TscnSection | null = parseSectionHeader(line, index);
+		if (section === null) {
+			if (currentNode !== null) {
+				const equalsIndex: number = line.indexOf("=");
+				if (equalsIndex > 0) {
+					const key: string = line.slice(0, equalsIndex).trim();
+					currentNode.properties[key] = line.slice(equalsIndex + 1).trim();
+					if (key === "script") {
+						currentNode.script = currentNode.properties[key] ?? null;
+					}
+				}
+			}
+			continue;
+		}
+
+		finishNode(index - 1);
+		if (section.type === "gd_scene") {
+			data.header = section;
+		} else if (section.type === "node") {
+			currentNode = {
+				name: unquoteTscnString(section.attributes.name),
+				type: unquoteTscnString(section.attributes.type),
+				parent: section.attributes.parent !== undefined ? unquoteTscnString(section.attributes.parent) : null,
+				instance: section.attributes.instance ?? null,
+				script: null,
+				properties: {},
+				lineStart: index,
+				lineEnd: index
+			};
+		} else if (section.type === "connection") {
+			data.connections.push({
+				signal: unquoteTscnString(section.attributes.signal),
+				from: unquoteTscnString(section.attributes.from),
+				to: unquoteTscnString(section.attributes.to),
+				method: unquoteTscnString(section.attributes.method),
+				flags: section.attributes.flags,
+				binds: section.attributes.binds,
+				lineIndex: index
+			});
+		}
+	}
+	finishNode(lines.length - 1);
+
+	return data;
+}
+
+export function validateTscnContent(content: string): string[] {
+	const errors: string[] = [];
+	const trimmedContent: string = content.trimStart();
+	if (!/^\[gd_scene\s/.test(trimmedContent)) {
+		errors.push("TSCN file must start with [gd_scene ...] header");
+	}
+	if (!/^\[node\s/m.test(trimmedContent)) {
+		errors.push("TSCN file must contain at least one [node ...] section (root node)");
+	}
+	return errors;
+}
+
+export function generateSceneTscn(rootNodeType: string, rootNodeName: string): string {
+	return [
+		"[gd_scene format=3]",
+		"",
+		`[node name="${quoteTscnString(rootNodeName)}" type="${quoteTscnString(rootNodeType)}"]`,
+		""
+	].join("\n");
+}
+
+export function getNodeFullPath(node: TscnNode, allNodes: TscnNode[]): string {
+	if (node.parent === null) {
+		return ".";
+	}
+	if (node.parent === ".") {
+		return node.name;
+	}
+	return `${node.parent}/${node.name}`;
+}
+
+export function findNodeInTscn(data: TscnData, targetPath: string): TscnNode | null {
+	const normalizedTarget: string = targetPath.trim() || ".";
+	for (const node of data.nodes) {
+		if (getNodeFullPath(node, data.nodes) === normalizedTarget || node.name === normalizedTarget && node.parent === null) {
+			return node;
+		}
+	}
+	return null;
+}
+
+function getNextSectionIndex(lines: string[], startIndex: number): number {
+	for (let index = startIndex; index < lines.length; index += 1) {
+		if (/^\[[a-zA-Z_]/.test(lines[index] ?? "")) {
+			return index;
+		}
+	}
+	return lines.length;
+}
+
+function findLastNodeInsertIndex(lines: string[]): number {
+	let insertIndex: number = lines.length;
+	for (let index = 0; index < lines.length; index += 1) {
+		if ((lines[index] ?? "").startsWith("[connection ")) {
+			return index;
+		}
+		if ((lines[index] ?? "").startsWith("[node ")) {
+			insertIndex = getNextSectionIndex(lines, index + 1);
+		}
+	}
+	return insertIndex;
+}
+
+function nodePathForChild(parentPath: string, nodeName: string): string {
+	return parentPath === "." ? nodeName : `${parentPath}/${nodeName}`;
+}
+
+export function addNodeToSceneTscn(content: string, parentPath: string, nodeType: string, nodeName: string, properties: Record<string, string>): string {
+	const data: TscnData = parseTscn(content);
+	const parentNode: TscnNode | null = findNodeInTscn(data, parentPath);
+	if (parentNode === null) {
+		throw new Error(`Parent node not found in scene: ${parentPath}`);
+	}
+	const candidatePath: string = nodePathForChild(parentPath, nodeName);
+	if (findNodeInTscn(data, candidatePath) !== null) {
+		throw new Error(`Node already exists in scene: ${candidatePath}`);
+	}
+
+	const lines: string[] = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+	const nodeLines: string[] = [
+		"",
+		`[node name="${quoteTscnString(nodeName)}" type="${quoteTscnString(nodeType)}" parent="${quoteTscnString(parentPath)}"]`
+	];
+	for (const [key, value] of Object.entries(properties)) {
+		nodeLines.push(`${key} = ${value}`);
+	}
+	lines.splice(findLastNodeInsertIndex(lines), 0, ...nodeLines);
+	return lines.join("\n");
+}
+
+export function attachScriptToSceneTscn(content: string, nodePath: string, scriptPath: string): string {
+	const data: TscnData = parseTscn(content);
+	const targetNode: TscnNode | null = findNodeInTscn(data, nodePath);
+	if (targetNode === null) {
+		throw new Error(`Node not found in scene: ${nodePath}`);
+	}
+	if (targetNode.script !== null) {
+		throw new Error(`Node already has a script: ${nodePath}`);
+	}
+	if (!scriptPath.startsWith("res://") && !scriptPath.startsWith("ExtResource(")) {
+		throw new Error("scriptPath must be a res:// path or an ExtResource reference");
+	}
+
+	const lines: string[] = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+	lines.splice(targetNode.lineEnd + 1, 0, `script = ${scriptPath.startsWith("ExtResource(") ? scriptPath : `ExtResource("${quoteTscnString(scriptPath)}")`}`);
+	return lines.join("\n");
+}
+
+export function connectSignalInSceneTscn(content: string, signal: string, fromNode: string, toNode: string, method: string, flags?: number, binds?: string): string {
+	const data: TscnData = parseTscn(content);
+	if (findNodeInTscn(data, fromNode) === null) {
+		throw new Error(`Signal source node not found in scene: ${fromNode}`);
+	}
+	if (findNodeInTscn(data, toNode) === null) {
+		throw new Error(`Signal target node not found in scene: ${toNode}`);
+	}
+	if (data.connections.some((connection: TscnConnection): boolean => connection.signal === signal && connection.from === fromNode && connection.to === toNode && connection.method === method)) {
+		throw new Error("This signal connection already exists in the scene");
+	}
+
+	const attrs: string[] = [
+		`signal="${quoteTscnString(signal)}"`,
+		`from="${quoteTscnString(fromNode)}"`,
+		`to="${quoteTscnString(toNode)}"`,
+		`method="${quoteTscnString(method)}"`
+	];
+	if (flags !== undefined) {
+		attrs.push(`flags=${flags}`);
+	}
+	if (binds !== undefined) {
+		attrs.push(`binds=${binds}`);
+	}
+
+	const lines: string[] = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+	if (lines.length > 0 && (lines[lines.length - 1] ?? "").trim().length > 0) {
+		lines.push("");
+	}
+	lines.push(`[connection ${attrs.join(" ")}]`);
+	return lines.join("\n");
+}
+
+export function applyScenePatchToTscn(content: string, operations: ScenePatchOperation[]): {
+	content: string;
+	applied: Array<{ type: string; target: string }>;
+} {
+	let nextContent: string = content;
+	const applied: Array<{ type: string; target: string }> = [];
+
+	for (const operation of operations) {
+		if (operation.type === "add_node") {
+			nextContent = addNodeToSceneTscn(nextContent, operation.parentPath, operation.nodeType, operation.nodeName, operation.properties ?? {});
+			applied.push({ type: operation.type, target: nodePathForChild(operation.parentPath, operation.nodeName) });
+		} else if (operation.type === "attach_script") {
+			nextContent = attachScriptToSceneTscn(nextContent, operation.nodePath, operation.scriptPath);
+			applied.push({ type: operation.type, target: operation.nodePath });
+		} else if (operation.type === "connect_signal") {
+			nextContent = connectSignalInSceneTscn(nextContent, operation.signal, operation.fromNode, operation.toNode, operation.method, operation.flags, operation.binds);
+			applied.push({ type: operation.type, target: `${operation.fromNode}.${operation.signal}` });
+		} else {
+			const unreachable: never = operation;
+			throw new Error(`Unsupported scene patch operation: ${JSON.stringify(unreachable)}`);
+		}
+	}
+
+	return { content: nextContent, applied };
+}

package/src/mcp/types.ts

@@ -0,0 +1,12 @@
+export type McpServerConfig = {
+	id: string;
+	name: string;
+	description?: string | undefined;
+	transport: "stdio" | "http";
+	command?: string | undefined;
+	args?: string[] | undefined;
+	env?: Record<string, string> | undefined;
+	url?: string | undefined;
+	headers?: Record<string, string> | undefined;
+	custom?: boolean | undefined;
+};

package/src/ping-client.ts

@@ -0,0 +1,24 @@
+import WebSocket from "ws";
+
+const url: string = process.env.WS_URL ?? "ws://localhost:8080";
+const socket: WebSocket = new WebSocket(url);
+
+socket.on("open", (): void => {
+	socket.send(JSON.stringify({
+		type: "request",
+		id: "test-1",
+		method: "ping",
+		params: {}
+	}));
+});
+
+socket.on("message", (data: WebSocket.RawData, isBinary: boolean): void => {
+	const text: string = isBinary ? data.toString("base64") : data.toString("utf8");
+	console.log(text);
+	socket.close();
+});
+
+socket.on("error", (error: Error): void => {
+	console.error("WebSocket client error:", error);
+	process.exitCode = 1;
+});

package/src/prompts/registry.ts

@@ -0,0 +1,97 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { PromptId } from "../protocol/types.js";
+
+export type PromptTemplate = {
+	id: PromptId;
+	name: string;
+	description: string;
+	path: string;
+};
+
+export const DEFAULT_PROMPT_ID: PromptId = "godot.assistant";
+
+export const promptTemplates: Record<PromptId, PromptTemplate> = {
+	"godot.assistant": {
+		id: "godot.assistant",
+		name: "Godot Assistant",
+		description: "General Godot Development Assistant",
+		path: "src/prompts/templates/godot-assistant.md"
+	},
+	"gdscript.reviewer": {
+		id: "gdscript.reviewer",
+		name: "GDScript Reviewer",
+		description: "Reviews GDScript code for type safety and style issues",
+		path: "src/prompts/templates/gdscript-reviewer.md"
+	},
+	"scene.architect": {
+		id: "scene.architect",
+		name: "Scene Architect",
+		description: "Designs Godot scene structures following scene-first principles",
+		path: "src/prompts/templates/scene-architect.md"
+	},
+	"backend.helper": {
+		id: "backend.helper",
+		name: "Backend Helper",
+		description: "TypeScript backend development for the AI Runtime",
+		path: "src/prompts/templates/backend-helper.md"
+	},
+};
+
+const promptContentCache: Map<PromptId, string> = new Map();
+const INSTRUCTION_PRIORITY_NOTICE: string = [
+	"冲突处理优先级：",
+	"1. Runtime 安全限制、后端强制策略、工具安全边界和审批流程。",
+	"2. 经 Runtime 工作区边界校验后加载的项目指令文件，例如 AGENTS.md、CLAUDE.md。",
+	"3. 用户当前消息中的明确任务目标。",
+	"4. 本 Settings 用户提示词。",
+	"5. 默认风格、通用建议和惯例。",
+	"",
+	"如果低优先级内容与高优先级内容冲突，只遵循不冲突的部分；必要时简短说明冲突原因。"
+].join("\n");
+
+const CUSTOM_INSTRUCTIONS_PRIORITY_NOTICE: string = [
+	"以下内容来自前端 Settings 的 Custom instructions，本轮请求会生效并随每次对话发送。",
+	"它只表示用户偏好或补充背景，不是工具结果、文件事实或项目规范。",
+	"如果它与系统规则、工具安全、项目指令文件或用户当前消息冲突，只遵循不冲突的部分。"
+].join("\n");
+
+const TOOL_CALL_COMMUNICATION_NOTICE: string = [
+	"工具调用沟通约定：",
+	"- 如果你决定调用工具，先用一句自然语言说明你马上要做什么，以及为什么这一步有必要。",
+	"- 预告应当简短、具体、像正常对话；不要输出工具协议、XML、DSML、JSON 参数或内部 tool_call 结构。",
+	"- 预告后直接发起工具调用，不要等待用户确认，除非工具安全策略或审批流程要求暂停。"
+].join("\n");
+
+export function listPromptTemplates(): PromptTemplate[] {
+	return Object.values(promptTemplates);
+}
+
+export async function loadPromptTemplate(promptId: PromptId): Promise<string> {
+	const cachedContent: string | undefined = promptContentCache.get(promptId);
+	if (cachedContent !== undefined) {
+		return cachedContent;
+	}
+
+	const template: PromptTemplate = promptTemplates[promptId];
+	const templatePath: string = resolve(process.cwd(), template.path);
+	const content: string = await readFile(templatePath, "utf8");
+	const trimmedContent: string = content.trim();
+	promptContentCache.set(promptId, trimmedContent);
+	return trimmedContent;
+}
+
+export async function composeSystemPrompt(
+	promptId: PromptId | undefined,
+	extraSystemPrompt: string | undefined
+): Promise<string> {
+	const templateContent: string = await loadPromptTemplate(promptId ?? DEFAULT_PROMPT_ID);
+	const trimmedExtraPrompt: string = extraSystemPrompt?.trim() ?? "";
+	const prioritizedTemplateContent: string = `${templateContent}\n\n## 工具调用沟通约定\n\n${TOOL_CALL_COMMUNICATION_NOTICE}\n\n## 指令优先级\n\n${INSTRUCTION_PRIORITY_NOTICE}`;
+
+	if (trimmedExtraPrompt.length === 0) {
+		return prioritizedTemplateContent;
+	}
+
+	return `${prioritizedTemplateContent}\n\n## Settings 用户提示词（本轮生效）\n\n${CUSTOM_INSTRUCTIONS_PRIORITY_NOTICE}\n\n${trimmedExtraPrompt}`;
+}

package/src/prompts/templates/backend-helper.md

@@ -0,0 +1,25 @@
+You are a TypeScript backend developer for the Godot Daedalus AI Runtime.
+The project is a Node.js WebSocket server that bridges Godot clients to LLM providers.
+
+Architecture:
+- `src/main.ts` — entry point
+- `src/protocol/` — types and zod schemas for the RPC protocol
+- `src/server/` — WebSocket server and JSON transport
+- `src/providers/` — LLM provider clients (DeepSeek, OpenAI, etc.)
+- `src/prompts/` — system prompt templates
+- `src/router/` — request routing by method
+- `src/godot/` — Godot project context reading
+
+Conventions:
+- All code in TypeScript with `strict` mode.
+- Use `zod` for runtime validation of all external input.
+- Use `verbatimModuleSyntax` — type-only imports must use `import type`.
+- Use NodeNext module resolution with `.js` extensions in imports.
+- UTF-8 without BOM, LF line endings.
+- Functions should have explicit return types.
+- External messages (WebSocket, HTTP) must be validated before acting on them.
+
+Key types:
+- ClientRequest: `{ type: "request", id: string } & ({ method: "ping" } | { method: "ai.chat", params: { message: string } })`
+- ServerResponse: discriminated union on `ok: true/false`
+- API keys stay on the backend only, never exposed to Godot clients.

package/src/prompts/templates/gdscript-reviewer.md

@@ -0,0 +1,19 @@
+You are a GDScript code reviewer for Godot projects.
+Follow these rules strictly:
+
+- All variables, parameters, and return types must use explicit static typing (`: int`, `: String`, etc.).
+- Never use inferred type assignment `:=`.
+- Do not repeat default initialization values (e.g., `var count: int` not `var count: int = 0`).
+- Parameters and local variables must not shadow member variables.
+- Prefer scene-tree paths over direct node variables when calling methods.
+- Static node properties (position, size, color, theme, etc.) must be set in `.tscn` files, not in `_ready()` or `_init()`.
+- Only runtime-dynamic properties should be set via script.
+- Signal connections between static nodes must be configured in the `.tscn` scene file, never in `_ready()`.
+- Use `uid://` resource paths when Godot provides stable UIDs.
+
+When reviewing code, point out:
+1. Missing type annotations.
+2. Shadowed variables.
+3. Static properties incorrectly set in scripts.
+4. Signal connections that should be in the scene file.
+5. Violations of GDScript style conventions.