godot-daedalus_backend 1.0.0

package/src/skills/registry.ts

@@ -0,0 +1,180 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { PromptId } from "../protocol/types.js";
+import { CUSTOM_MCP_TOOLS_SENTINEL } from "../tools/llm-tools.js";
+
+export const skillIds = [
+	"godot.project_init",
+	"gdscript.review",
+	"scene.builder",
+	"file.creator",
+	"backend.helper"
+] as const;
+
+export type SkillId = typeof skillIds[number];
+
+export type Skill = {
+	id: SkillId;
+	name: string;
+	description: string;
+	promptPath: string;
+	defaultPromptId?: PromptId;
+	allowedTools: string[];
+};
+
+const READ_TOOLS: string[] = [
+	"mcp_godot_get_project_summary",
+	"mcp_godot_list_project_files",
+	"mcp_godot_list_scenes",
+	"mcp_godot_list_scripts",
+	"mcp_godot_read_text_file",
+	"mcp_godot_search_text",
+	"mcp_godot_get_project_log_config",
+	"mcp_godot_list_project_logs",
+	"mcp_godot_read_project_log",
+	"mcp_godot_get_project_settings",
+	"mcp_godot_get_editor_config_summary",
+	"mcp_godot_get_editor_settings",
+	"mcp_godot_list_editor_config_files",
+	"mcp_godot_read_editor_config_file",
+	"mcp_godot_get_editor_project_state",
+	"mcp_godot_get_recent_projects",
+	"mcp_godot_inspect_scene_tree",
+	"mcp_godot_editor_get_context",
+	"mcp_godot_editor_get_selected_nodes",
+	"mcp_godot_editor_inspect_node",
+	"mcp_godot_lsp_get_status",
+	"mcp_godot_lsp_get_file_diagnostics",
+	"mcp_godot_lsp_get_document_symbols",
+	"mcp_godot_lsp_hover",
+	"mcp_godot_lsp_goto_definition",
+	"mcp_godot_dap_get_status",
+	"mcp_godot_dap_get_last_error",
+	"mcp_godot_dap_get_stack_trace",
+	"mcp_godot_dap_get_variables",
+	CUSTOM_MCP_TOOLS_SENTINEL
+];
+
+const FILE_CREATE_TOOLS: string[] = [
+	"mcp_godot_create_text_file"
+];
+
+const VERIFY_TOOLS: string[] = [
+	"mcp_godot_lsp_get_file_diagnostics",
+	"mcp_terminal_get_capabilities",
+	"mcp_terminal_run_safe_preset"
+];
+
+const TERMINAL_WRITE_TOOLS: string[] = [
+	"mcp_terminal_run_write_preset",
+	"mcp_terminal_run_godot_scene_script"
+];
+
+const FILE_EDIT_TOOLS: string[] = [
+	"mcp_godot_overwrite_text_file",
+	"mcp_godot_replace_text_in_file",
+	"mcp_godot_propose_set_project_setting",
+	"mcp_godot_set_project_setting",
+	"mcp_godot_propose_unset_project_setting",
+	"mcp_godot_unset_project_setting"
+];
+
+const SCENE_WRITE_TOOLS: string[] = [
+	"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"
+];
+
+const skills: Record<SkillId, Skill> = {
+	"godot.project_init": {
+		id: "godot.project_init",
+		name: "Godot Project Init",
+		description: "Inspect the Godot project and create an AGENTS.md project guide.",
+		promptPath: "src/skills/templates/godot-project-init.md",
+		defaultPromptId: "godot.assistant",
+		allowedTools: [...READ_TOOLS, ...FILE_CREATE_TOOLS, ...FILE_EDIT_TOOLS, ...VERIFY_TOOLS, ...TERMINAL_WRITE_TOOLS]
+	},
+	"gdscript.review": {
+		id: "gdscript.review",
+		name: "GDScript Review",
+		description: "Review GDScript for type safety, Godot lifecycle issues, signals, and style.",
+		promptPath: "src/skills/templates/gdscript-review.md",
+		defaultPromptId: "gdscript.reviewer",
+		allowedTools: [...READ_TOOLS, ...VERIFY_TOOLS]
+	},
+	"scene.builder": {
+		id: "scene.builder",
+		name: "Scene Builder",
+		description: "Plan Godot scene structures and node responsibilities.",
+		promptPath: "src/skills/templates/scene-builder.md",
+		defaultPromptId: "scene.architect",
+		allowedTools: [...READ_TOOLS, ...SCENE_WRITE_TOOLS, ...FILE_CREATE_TOOLS, ...VERIFY_TOOLS]
+	},
+	"file.creator": {
+		id: "file.creator",
+		name: "File Creator",
+		description: "Create new project files through approval-gated tools.",
+		promptPath: "src/skills/templates/file-creator.md",
+		defaultPromptId: "godot.assistant",
+		allowedTools: [...READ_TOOLS, ...FILE_CREATE_TOOLS, ...FILE_EDIT_TOOLS, ...VERIFY_TOOLS, ...TERMINAL_WRITE_TOOLS]
+	},
+	"backend.helper": {
+		id: "backend.helper",
+		name: "Backend Helper",
+		description: "Work on the TypeScript WebSocket/MCP backend.",
+		promptPath: "src/skills/templates/backend-helper.md",
+		defaultPromptId: "backend.helper",
+		allowedTools: [...READ_TOOLS, ...VERIFY_TOOLS]
+	}
+};
+
+const skillPromptCache: Map<SkillId, string> = new Map();
+
+export function listSkills(): Skill[] {
+	return Object.values(skills);
+}
+
+export function isSkillId(value: string): value is SkillId {
+	return (skillIds as readonly string[]).includes(value);
+}
+
+export function getSkill(skillId: SkillId): Skill {
+	return skills[skillId];
+}
+
+export async function loadSkillPrompt(skillId: SkillId): Promise<string> {
+	const cachedPrompt: string | undefined = skillPromptCache.get(skillId);
+	if (cachedPrompt !== undefined) {
+		return cachedPrompt;
+	}
+
+	const skill: Skill = getSkill(skillId);
+	const content: string = await readFile(resolve(process.cwd(), skill.promptPath), "utf8");
+	const trimmedContent: string = content.trim();
+	skillPromptCache.set(skillId, trimmedContent);
+	return trimmedContent;
+}
+
+export async function composeSkillPrompt(skillId: SkillId | undefined): Promise<string> {
+	if (skillId === undefined) {
+		return "";
+	}
+
+	const skill: Skill = getSkill(skillId);
+	const prompt: string = await loadSkillPrompt(skillId);
+	return [
+		"## 当前激活 Skill",
+		`- ID: ${skill.id}`,
+		`- 名称: ${skill.name}`,
+		`- 描述: ${skill.description}`,
+		"- 允许工具:",
+		...skill.allowedTools
+			.filter((toolName: string): boolean => toolName !== CUSTOM_MCP_TOOLS_SENTINEL)
+			.map((toolName: string): string => `  - ${toolName}`),
+		"",
+		prompt
+	].join("\n");
+}

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

@@ -0,0 +1,12 @@
+# Backend Helper Skill
+
+你负责 TypeScript WebSocket/MCP 后端开发。
+
+重点：
+
+- 保持协议结构清晰，优先使用 Zod schema。
+- 工具调用必须经过审批/策略层。
+- 不让客户端绕过审批直接执行写操作。
+- 变更后运行 `npm run typecheck`。
+
+回答时优先指出具体文件、协议字段和验证方式。

package/src/skills/templates/file-creator.md

@@ -0,0 +1,14 @@
+# File Creator Skill
+
+你负责创建新文件。必须遵守 Runtime 文件能力和审批规则。
+
+流程：
+
+1. 明确文件路径和用途。
+2. 确保路径在项目内，且不是 `.godot/`、`addons/` 或隐藏目录。
+3. 创建或修改文件时调用实际写入工具，不要把 `propose_*` 当作实现结果。
+4. 修改 `project.godot` 项目设置时，先读取当前设置并调用 `propose_*` 预览，再调用实际 set/unset 工具。
+5. 实际写入工具需要审批时，后端会暂停本轮并向客户端发送审批事件；不要继续总结成“已完成”。
+6. 文件创建或修改成功后，读取文件确认内容。
+
+不能覆盖、删除或伪造文件修改结果。

package/src/skills/templates/gdscript-review.md

@@ -0,0 +1,12 @@
+# GDScript Review Skill
+
+你负责审查 GDScript 代码。先读取目标文件和必要的相邻文件，再输出风险优先的审查结果。
+
+重点检查：
+
+- 强类型、禁止 `:=`、变量遮蔽。
+- Godot 生命周期、节点有效性、信号连接。
+- `res://`、`uid://`、`user://` 路径使用。
+- 场景节点结构和脚本职责是否匹配。
+
+不要修改文件。需要修改时只给出结构化建议，除非用户明确要求进入文件创建流程。

package/src/skills/templates/godot-project-init.md

@@ -0,0 +1,29 @@
+# Godot Project Init Skill
+
+你的任务是初始化当前 Godot 项目的 AI 协作上下文，并生成项目根目录的 `AGENTS.md`。
+
+执行流程：
+
+1. 先读取项目摘要、场景列表、脚本列表和关键配置。
+2. 如有必要，读取少量代表性 `.gd`、`.tscn`、`.tres`、`project.godot` 文件来判断项目结构。
+3. 生成一份简洁、可执行的 `AGENTS.md`，面向后续 AI/开发者协作。
+4. 如果项目根目录不存在 `AGENTS.md`，调用文件创建工具创建它。
+5. 如果 `AGENTS.md` 已存在，不要覆盖；先读取它，说明已有内容，并提出是否需要用户确认后再更新。
+
+`AGENTS.md` 应包含：
+
+- 项目概览
+- 目录结构与主要文件
+- Godot/GDScript 编码规范
+- 场景与资源修改规则
+- 测试与验证命令
+- AI 工具使用与审批规则
+- 不允许修改的目录或文件
+
+写作要求：
+
+- 使用 Markdown。
+- 内容应基于实际项目，不要泛泛而谈。
+- 保持 200-600 词左右，除非项目复杂度要求更长。
+- 不能声称文件已创建，除非工具明确返回创建成功。
+- 如果创建工具返回需要审批，提醒用户在 Godot 客户端 Approvals 区域批准。

package/src/skills/templates/scene-builder.md

@@ -0,0 +1,12 @@
+# Scene Builder Skill
+
+你负责规划 Godot 场景结构。优先使用场景节点、Inspector 属性和信号连接表达固定关系。
+
+输出时说明：
+
+- 推荐节点树。
+- 每个关键节点的职责。
+- 哪些属性应放在 `.tscn`，哪些逻辑应放在脚本。
+- 需要的脚本、资源和信号连接。
+
+不要假设已修改场景；只有实际写入工具成功返回后，才能说场景或脚本已经生效。实际写入工具触发审批时，后端会暂停本轮并向客户端发送审批事件。

package/src/tokens/deepseek-tokenizer-counter.ts

@@ -0,0 +1,233 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { TokenCounter } from "./token-counter.js";
+import type { ChatMessage } from "../protocol/types.js";
+
+const PACKAGE_ROOT: string = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const TOKENIZER_SCRIPT: string = resolve(PACKAGE_ROOT, "scripts/deepseek-tokenizer-server.py");
+const DEFAULT_TOKENIZER_DIR: string = resolve(PACKAGE_ROOT, "scripts/tokenizer");
+const START_TIMEOUT_MS: number = 30_000;
+const REQUEST_TIMEOUT_MS: number = 10_000;
+
+type PendingRequest = {
+	resolve: (tokens: number) => void;
+	reject: (error: Error) => void;
+	timeout: ReturnType<typeof setTimeout>;
+};
+
+export class DeepSeekTokenizerCounter implements TokenCounter {
+	private process: ChildProcess | null = null;
+	private pending: Map<number, PendingRequest> = new Map();
+	private requestId: number = 0;
+	private ready: boolean = false;
+	private initPromise: Promise<void> | null = null;
+
+	async initialize(): Promise<void> {
+		if (this.initPromise) {
+			return this.initPromise;
+		}
+
+		this.initPromise = this.startProcess();
+		return this.initPromise;
+	}
+
+	private startProcess(): Promise<void> {
+		return new Promise<void>((resolvePromise, rejectPromise) => {
+			const tokenizerDir: string = process.env.DEEPSEEK_TOKENIZER_DIR ?? DEFAULT_TOKENIZER_DIR;
+			const pythonCmd: string = process.env.PYTHON_CMD ?? "python";
+			let startupSettled: boolean = false;
+
+			const child: ChildProcess = spawn(pythonCmd, [TOKENIZER_SCRIPT, tokenizerDir], {
+				env: {
+					...process.env,
+					PYTHONIOENCODING: "utf-8",
+					PYTHONUTF8: "1"
+				},
+				stdio: ["pipe", "pipe", "pipe"]
+			});
+
+			const startTimeout: ReturnType<typeof setTimeout> = setTimeout((): void => {
+				rejectStartup(new Error("Tokenizer startup timed out. Install tokenizers: pip install tokenizers"));
+			}, START_TIMEOUT_MS);
+
+			const resolveStartup = (): void => {
+				if (startupSettled) {
+					return;
+				}
+
+				startupSettled = true;
+				clearTimeout(startTimeout);
+				resolvePromise();
+			};
+
+			const rejectStartup = (error: Error): void => {
+				if (startupSettled) {
+					return;
+				}
+
+				startupSettled = true;
+				clearTimeout(startTimeout);
+				rejectPromise(error);
+			};
+
+			const rl = createInterface({ input: child.stdout! });
+
+			rl.on("line", (line: string): void => {
+				const trimmed: string = line.trim();
+				if (trimmed.length === 0) {
+					return;
+				}
+
+				try {
+					const response: { id?: number; ready?: boolean; tokens?: number; error?: string } = JSON.parse(trimmed) as {
+						id?: number; ready?: boolean; tokens?: number; error?: string;
+					};
+
+					if (response.ready === true) {
+						this.ready = true;
+						resolveStartup();
+						return;
+					}
+
+					if (response.error) {
+						const error: Error = new Error(response.error);
+						if (!this.ready) {
+							rejectStartup(error);
+							return;
+						}
+
+						if (response.id !== undefined) {
+							this.rejectPending(response.id, error);
+						} else {
+							this.rejectAll(error);
+						}
+						return;
+					}
+
+					if (response.tokens !== undefined) {
+						if (response.id !== undefined) {
+							this.resolvePending(response.id, response.tokens);
+						} else {
+							this.resolveFirstPending(response.tokens);
+						}
+					}
+				} catch {
+					// Non-JSON output from Python — ignore (e.g., warnings)
+				}
+			});
+
+			child.stderr?.on("data", (data: Buffer): void => {
+				console.error("[tokenizer]", data.toString("utf8").trimEnd());
+			});
+
+			child.on("error", (error: Error): void => {
+				this.ready = false;
+				this.process = null;
+				this.initPromise = null;
+				rejectStartup(error);
+				this.rejectAll(error);
+			});
+
+			child.on("close", (): void => {
+				this.ready = false;
+				this.process = null;
+				this.initPromise = null;
+				const error: Error = new Error("Tokenizer process exited");
+				rejectStartup(error);
+				this.rejectAll(error);
+			});
+
+			this.process = child;
+		});
+	}
+
+	private sendRequest(text: string): Promise<number> {
+		return new Promise<number>((resolve, reject) => {
+			if (!this.process?.stdin?.writable) {
+				reject(new Error("Tokenizer process is not writable"));
+				return;
+			}
+
+			const id: number = this.requestId;
+			this.requestId += 1;
+
+			const timeout: ReturnType<typeof setTimeout> = setTimeout((): void => {
+				this.pending.delete(id);
+				reject(new Error("Tokenizer request timed out"));
+			}, REQUEST_TIMEOUT_MS);
+
+			this.pending.set(id, { resolve, reject, timeout });
+
+			this.process.stdin.write(JSON.stringify({ id, text }) + "\n", (error: Error | null | undefined): void => {
+				if (error !== null && error !== undefined) {
+					this.rejectPending(id, error);
+				}
+			});
+		});
+	}
+
+	private resolvePending(id: number, tokens: number): void {
+		const pending: PendingRequest | undefined = this.pending.get(id);
+		if (pending === undefined) {
+			return;
+		}
+
+		clearTimeout(pending.timeout);
+		pending.resolve(tokens);
+		this.pending.delete(id);
+	}
+
+	private resolveFirstPending(tokens: number): void {
+		for (const [id, pending] of this.pending) {
+			clearTimeout(pending.timeout);
+			pending.resolve(tokens);
+			this.pending.delete(id);
+			return;
+		}
+	}
+
+	private rejectPending(id: number, error: Error): void {
+		const pending: PendingRequest | undefined = this.pending.get(id);
+		if (pending === undefined) {
+			return;
+		}
+
+		clearTimeout(pending.timeout);
+		pending.reject(error);
+		this.pending.delete(id);
+	}
+
+	private rejectAll(error: Error): void {
+		for (const [id, pending] of this.pending) {
+			clearTimeout(pending.timeout);
+			pending.reject(error);
+			this.pending.delete(id);
+		}
+	}
+
+	async countText(text: string): Promise<number> {
+		if (!this.ready) {
+			await this.initialize();
+		}
+
+		return this.sendRequest(text);
+	}
+
+	async countMessages(messages: ChatMessage[]): Promise<number> {
+		const combined: string = messages.map((m: ChatMessage): string => m.content).join("\n");
+		const baseTokens: number = await this.countText(combined);
+		return baseTokens + messages.length * 4;
+	}
+
+	async dispose(): Promise<void> {
+		if (this.process) {
+			this.process.stdin?.end();
+			this.process.kill();
+			this.process = null;
+		}
+
+		this.ready = false;
+	}
+}

package/src/tokens/model-profiles.ts

@@ -0,0 +1,38 @@
+import type { ModelProfile } from "../protocol/types.js";
+
+export const DEEPSEEK_V4_FLASH: ModelProfile = {
+	provider: "deepseek",
+	model: "deepseek-v4-flash",
+	contextWindowTokens: 1_000_000,
+	maxOutputTokens: 384_000,
+	defaultOutputReserveTokens: 16_000,
+	safetyMarginTokens: 8_000,
+};
+
+export const DEEPSEEK_V4_PRO: ModelProfile = {
+	provider: "deepseek",
+	model: "deepseek-v4-pro",
+	contextWindowTokens: 1_000_000,
+	maxOutputTokens: 384_000,
+	defaultOutputReserveTokens: 32_000,
+	safetyMarginTokens: 12_000,
+};
+
+const MODEL_REGISTRY: Record<string, ModelProfile> = {
+	"deepseek-v4-flash": DEEPSEEK_V4_FLASH,
+	"deepseek-v4-pro": DEEPSEEK_V4_PRO,
+};
+
+export function resolveModelProfile(modelName: string): ModelProfile {
+	const profile: ModelProfile | undefined = MODEL_REGISTRY[modelName];
+
+	if (!profile) {
+		throw new Error(`Unknown model: ${modelName}`);
+	}
+
+	return profile;
+}
+
+export function getDefaultModelProfile(): ModelProfile {
+	return DEEPSEEK_V4_FLASH;
+}

package/src/tokens/token-counter-factory.ts

@@ -0,0 +1,52 @@
+import type { TokenCounter } from "./token-counter.js";
+import { ApproxTokenCounter } from "./token-counter.js";
+import type { ChatMessage } from "../protocol/types.js";
+
+class ResilientTokenCounter implements TokenCounter {
+	constructor(
+		private readonly primary: TokenCounter,
+		private readonly fallback: TokenCounter
+	) {}
+
+	async countText(text: string): Promise<number> {
+		try {
+			return await this.primary.countText(text);
+		} catch (error: unknown) {
+			const message: string = error instanceof Error ? error.message : String(error);
+			console.warn(`[token-counter] Precise count failed, using approximate count: ${message}`);
+			return this.fallback.countText(text);
+		}
+	}
+
+	async countMessages(messages: ChatMessage[]): Promise<number> {
+		try {
+			return await this.primary.countMessages(messages);
+		} catch (error: unknown) {
+			const message: string = error instanceof Error ? error.message : String(error);
+			console.warn(`[token-counter] Precise message count failed, using approximate count: ${message}`);
+			return this.fallback.countMessages(messages);
+		}
+	}
+}
+
+export async function createTokenCounter(): Promise<TokenCounter> {
+	const disableTokenizer: string | undefined = process.env.DISABLE_DEEPSEEK_TOKENIZER;
+	const fallback: ApproxTokenCounter = new ApproxTokenCounter();
+
+	if (disableTokenizer === "1" || disableTokenizer === "true") {
+		return fallback;
+	}
+
+	try {
+		const { DeepSeekTokenizerCounter } = await import("./deepseek-tokenizer-counter.js");
+		const counter = new DeepSeekTokenizerCounter();
+		await counter.initialize();
+		console.log("[token-counter] Using DeepSeekTokenizerCounter (Python)");
+		return new ResilientTokenCounter(counter, fallback);
+	} catch (error: unknown) {
+		const message: string = error instanceof Error ? error.message : String(error);
+		console.warn(`[token-counter] DeepSeek tokenizer unavailable: ${message}`);
+		console.warn("[token-counter] Falling back to ApproxTokenCounter (char/3 estimate)");
+		return fallback;
+	}
+}

package/src/tokens/token-counter.ts

@@ -0,0 +1,22 @@
+import type { ChatMessage } from "../protocol/types.js";
+
+export type TokenCounter = {
+	countText(text: string): Promise<number>;
+	countMessages(messages: ChatMessage[]): Promise<number>;
+};
+
+export class ApproxTokenCounter implements TokenCounter {
+	async countText(text: string): Promise<number> {
+		return Math.max(1, Math.ceil(text.length / 3));
+	}
+
+	async countMessages(messages: ChatMessage[]): Promise<number> {
+		let total: number = 0;
+
+		for (const message of messages) {
+			total += await this.countText(message.content) + 4;
+		}
+
+		return total;
+	}
+}