dsh-unity-mcp 0.0.7 → 0.0.9

package/README.md

@@ -32,7 +32,7 @@ Agent 加载工具后，先用 `unity_project` 的 `list` 查看打开的工程
 
 安装 CoderGamester 和保存 DSH 连接分别由独立工具处理，避免把打开工程、修改包和切换所有会话的连接混为一次操作。工程处于关闭状态时，也可以先离线准备安装，再打开编辑器。包依赖固定在已核验的上游 commit，已有不同的 CoderGamester 依赖时不会擅自替换；其他包会保留。
 
-**打开工程需要时间。** 工具会等待编辑器完成当前导入、编译并回应新鲜握手：返回 `editor_ready` / `editorReady: true` 才代表这次编辑器就绪检查通过。`list` 中的 `running_not_verified` 只表示发现了进程。`status` 返回 `readiness_unconfirmed` 或 `open` 返回 `editor_loading` 时，应继续检查或等待，不要重复启动或假设工程已经加载完成。运行或启动中的工程，安装工具也会在修改依赖前执行就绪检查；等待失败不会改写依赖。关闭工程的离线安装只代表文件准备完成，不代表工程已打开。
+**打开工程需要时间。** 工具会等待编辑器完成当前导入、编译并回应新鲜握手：返回 `editor_ready` / `editorReady: true` 才代表这次编辑器就绪检查通过。`list` 中的 `running_not_verified` 只表示发现了进程。`status` 或 `open` 返回 `readiness_unconfirmed` 时，`running: true` 表示已发现该工程进程，`editorReady: null` 表示未能确认就绪，不能据此断定仍在加载。`process_unconfirmed` 表示部分进程的工程路径不可读，不能确认该工程是否运行。不要重复启动；可先截图查看编辑器。运行或启动中的工程，安装工具也会在修改依赖前执行就绪检查；等待失败不会改写依赖。关闭工程的离线安装只代表文件准备完成，不代表工程已打开。
 
 编辑器就绪仍不等于 MCP 连通。Package Manager 还需下载和编译引擎包，服务需要成功启动；Node 服务器缺少构建文件时，还需在其 `Server~` 目录执行 `npm install` 和 `npm run build`。安装工具不会代为下载或构建 Node 服务器，也不自动改变 DSH 连接。
 
@@ -91,7 +91,8 @@ Agent 加载工具后，先用 `unity_project` 的 `list` 查看打开的工程
 
 ## 排障
 
-- **工程一直是 `editor_loading`**：检查编辑器中的包解析、编译错误、模态窗口或自动刷新；修复后继续等待。不要因为超时就再次启动编辑器。
+- **工程就绪检查一直未确认**：进程已发现时不会据此报为“仍在加载”。用 `unity_capture_window` 并指定 `projectPath` 查看编辑器面板，再检查包解析、编译错误、模态窗口或自动刷新；不要因为超时再次启动编辑器。
+- **查看编辑器窗口**：懒加载后可调用 `unity_capture_window({projectPath: "C:/Projects/MyGame"})`，不依赖 MCP 或 Editor 桥接。仅支持 Windows，返回指定工程主窗口的图片附件，不抓桌面、不切换焦点、不还原最小化窗口。最小化、窗口不可用会报错；GPU 视图可能黑屏或未刷新，主窗口截图也不保证包含独立弹窗。截图可能包含工程中的敏感内容。工具仅为截图 PowerShell 子进程指定 `-ExecutionPolicy Bypass`，不修改系统或用户策略。
 - **安装等待失败**：运行中的工程尚未回应就绪检查，依赖未修改。先让工程完成加载；若修改过桥接源码，需人工处理冲突。
 - **Built CoderGamester server not found**：确认引擎包已经安装且 Node 服务器已构建，或手工设置 `serverPath`。
 - **Multiple cached CoderGamester servers found**：明确选择 `serverPath`。

package/index.mjs

@@ -4,9 +4,10 @@ import { connectionConfig } from './lib/connection.mjs';
 import { installLazyTools } from './lib/lazy-tools.mjs';
 import { projectTool } from './lib/project.mjs';
 import { installationTool } from './lib/install-codergamester.mjs';
+import { screenshotTool } from './lib/capture-window.mjs';
 import { configurationTool } from './lib/configure-project.mjs';
 export const name = 'dsh-unity-mcp';
-export const inject = ['tools', 'agents', 'configEditor'];
+export const inject = ['tools', 'agents', 'configEditor', 'attachments'];
 export const Config = z.object({
   projectPath: z.string().default('').description('Unity / Tuanjie 项目绝对路径 / Absolute project directory'),
   serverPath: z.string().default('').description('CoderGamester Server~/build/index.js 绝对路径；留空从项目发现 / Built server path; blank discovers in project'),
@@ -18,7 +19,7 @@ export const Config = z.object({
 });
 export async function apply(ctx, config) {
   // Install the loader even before configuration, so discovery explains setup.
-  installLazyTools(ctx, config.lazyTools, [projectTool(ctx), installationTool(), configurationTool(ctx)]);
+  installLazyTools(ctx, config.lazyTools, [projectTool(ctx), screenshotTool(ctx), installationTool(), configurationTool(ctx)]);
   if (!config.projectPath && !config.serverPath) {
     ctx.logger.info('Unity MCP: configure projectPath or serverPath to connect CoderGamester/mcp-unity.');
     return;

package/lib/capture-window.mjs

@@ -0,0 +1,35 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { matchingProcess, projectRoot } from './project-lifecycle.mjs';
+const exec = promisify(execFile);
+export async function captureWindow(pid) {
+  const { stdout } = await exec('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', fileURLToPath(new URL('./capture-window.ps1', import.meta.url)), '-EditorPid', String(pid)], { windowsHide: true, timeout: 20000, maxBuffer: 12 * 1024 * 1024 });
+  return JSON.parse(stdout.replace(/^\uFEFF/, '').trim());
+}
+export async function captureProject(input, deps = {}) {
+  if ((deps.platform ?? process.platform) !== 'win32') throw Error('Editor window capture currently supports Windows only.');
+  if (!input || Object.keys(input).some(key => key !== 'projectPath')) throw Error('Capture accepts only projectPath.');
+  const root = await projectRoot(input.projectPath);
+  const editor = await matchingProcess(root, deps.processes);
+  if (!editor) throw Error('No matching editor process. Use unity_project action=list to inspect running editors.');
+  const image = await (deps.capture ?? captureWindow)(editor.ProcessId);
+  if (image.pid !== editor.ProcessId) throw Error('Screenshot process identity mismatch.');
+  const after = await matchingProcess(root, deps.processes);
+  if (after?.ProcessId !== editor.ProcessId) throw Error('Editor changed during capture; screenshot discarded.');
+  const data = Buffer.from(image.data ?? '', 'base64');
+  if (data.length < 24 || data.length > 8 * 1024 * 1024 || data.subarray(0, 8).toString('hex') !== '89504e470d0a1a0a' || data.toString('base64') !== image.data) throw Error('Invalid PNG window capture.');
+  if (data.readUInt32BE(16) !== image.width || data.readUInt32BE(20) !== image.height) throw Error('Screenshot dimensions mismatch.');
+  return { projectPath: root, pid: editor.ProcessId, title: image.title, width: image.width, height: image.height, method: image.method, data };
+}
+export function screenshotTool(ctx, deps = {}) {
+  return { name: 'unity_capture_window', description: 'Capture the main Windows Unity/Tuanjie editor window for an explicit project, including editor panels, without MCP or an Editor bridge. Returns an image. Does not focus/restore windows or capture the desktop. Minimized or unavailable windows fail; GPU-rendered views may be black or stale.',
+    parameters: { type: 'object', properties: { projectPath: { type: 'string', description: 'Absolute directory of the open project. Use unity_project action=list to select it.' } }, required: ['projectPath'], additionalProperties: false },
+    output: { schema: { type: 'object' }, render: (_, value) => [{ type: 'text', text: JSON.stringify({ ...value, attachment: undefined }) }, { type: 'image', attachment: value.attachment }] },
+    execute: async input => {
+      const { data, ...metadata } = await captureProject(input, deps);
+      const attachment = await ctx.attachments.saveImage({ data, mediaType: 'image/png', name: 'unity-editor.png' });
+      return { ...metadata, attachment };
+    }
+  };
+}

package/lib/capture-window.ps1

@@ -0,0 +1,40 @@
+param([int]$EditorPid)
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+Add-Type -AssemblyName System.Drawing
+Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+public static class DshEditorCapture {
+ [StructLayout(LayoutKind.Sequential)] public struct Rect { public int Left, Top, Right, Bottom; }
+ [DllImport("user32.dll")] public static extern bool GetWindowRect(IntPtr h, out Rect r);
+ [DllImport("user32.dll")] public static extern bool IsIconic(IntPtr h);
+ [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr h);
+ [DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr h, out uint pid);
+ [DllImport("user32.dll")] public static extern bool PrintWindow(IntPtr h, IntPtr dc, uint flags);
+ [DllImport("user32.dll")] public static extern bool SetProcessDPIAware();
+}
+'@
+[void][DshEditorCapture]::SetProcessDPIAware()
+$p = Get-Process -Id $EditorPid -ErrorAction Stop
+$h = $p.MainWindowHandle
+if ($h -eq [IntPtr]::Zero -or -not [DshEditorCapture]::IsWindowVisible($h)) { throw 'Editor has no visible main window yet.' }
+if ([DshEditorCapture]::IsIconic($h)) { throw 'Editor window is minimized. Restore it before capture; no desktop fallback was used.' }
+[uint32]$ownerId = 0
+[void][DshEditorCapture]::GetWindowThreadProcessId($h, [ref]$ownerId)
+if ($ownerId -ne $EditorPid) { throw 'Window process identity changed.' }
+$r = New-Object DshEditorCapture+Rect
+if (-not [DshEditorCapture]::GetWindowRect($h, [ref]$r)) { throw 'Cannot read editor window bounds.' }
+$w = $r.Right - $r.Left; $height = $r.Bottom - $r.Top
+if ($w -lt 1 -or $height -lt 1 -or $w -gt 8192 -or $height -gt 8192 -or [long]$w * $height -gt 24000000) { throw 'Editor window dimensions exceed capture limits.' }
+$bitmap = New-Object System.Drawing.Bitmap($w, $height)
+$graphics = [System.Drawing.Graphics]::FromImage($bitmap)
+$stream = New-Object System.IO.MemoryStream
+try {
+ $dc = $graphics.GetHdc()
+ try { $ok = [DshEditorCapture]::PrintWindow($h, $dc, 2) } finally { $graphics.ReleaseHdc($dc) }
+ if (-not $ok) { throw 'Window capture failed; no desktop fallback was used.' }
+ $bitmap.Save($stream, [System.Drawing.Imaging.ImageFormat]::Png)
+ if ($stream.Length -gt 8388608) { throw 'Screenshot exceeds 8 MiB.' }
+ @{ pid=$EditorPid; title=$p.MainWindowTitle; width=$w; height=$height; data=[Convert]::ToBase64String($stream.ToArray()); method='PrintWindow' } | ConvertTo-Json -Compress
+} finally { $graphics.Dispose(); $bitmap.Dispose(); $stream.Dispose() }

package/lib/lazy-tools.mjs

@@ -9,6 +9,9 @@ export function installLazyTools(ctx, lazy = true, setupTools = []) {
     if (states.has(agent)) return;
     const state = { loaded: !lazy, signature: '', disposers: [], tools: [] };
     const refresh = () => {
+      if (state.disposed || state.refreshing) return;
+      state.refreshing = true;
+      try {
       const raw = rawDefinitions();
       const defs = [...setupTools, ...createEngineTools(raw)], signature = JSON.stringify(defs.map(({ name, description, parameters }) => ({ name, description, parameters })));
       if (signature === state.signature && raw.length === state.raw?.length && raw.every((tool, i) => tool === state.raw[i])) return;
@@ -24,9 +27,12 @@ export function installLazyTools(ctx, lazy = true, setupTools = []) {
         state.tools.push(...installed);
       }
       state.signature = signature;
+      } finally { state.refreshing = false; }
     };
     state.refresh = refresh;
     state.dispose = agent.ctx.effect(() => () => {
+      state.disposed = true;
+      states.delete(agent);
       for (const dispose of state.tools.splice(0).reverse()) dispose();
       state.mask?.();
       for (const dispose of state.disposers.splice(0).reverse()) dispose();
@@ -46,6 +52,15 @@ export function installLazyTools(ctx, lazy = true, setupTools = []) {
     }));
     refresh();
   }
+  // MCP discovery completes asynchronously, potentially before the first pre-step.
+  // Own registrations/restrictions also emit tools/change: suppress nested refreshes.
+  let syncing = false;
+  ctx.on('tools/change', () => {
+    if (syncing) return;
+    syncing = true;
+    try { for (const state of states.values()) state.refresh(); }
+    finally { syncing = false; }
+  });
   ctx.on('agent/created', ({ agent }) => { attach(agent); });
   ctx.on('agent/pre-step', ({ agent }, next) => { attach(agent); states.get(agent).refresh(); return next(); });
   for (const agent of ctx.agents.list()) attach(agent);

package/lib/open-project.mjs

@@ -21,11 +21,12 @@ async function finishOpen(result, input, deps) {
     await (deps.waitReady ?? waitForEditor)(result.projectPath, input.timeoutMs ?? 120000, deps);
     return { ...result, status: 'editor_ready', editorReady: true, message: 'Editor responded after import/compilation settled. MCP connectivity is not verified.' };
   } catch (error) {
-    return { ...result, status: 'editor_loading', editorReady: false, message: 'Not ready: ' + error.message + ' Do not assume loading finished. Retry unity_project action=status or open to wait again; do not relaunch or configure MCP yet.' };
+    return { ...result, status: 'readiness_unconfirmed', running: true, editorReady: null, message: 'Editor process was found or launched, but readiness is unconfirmed: ' + error.message + ' This does not prove it is loading or stopped. Inspect the editor window or retry unity_project action=status; do not relaunch.' };
   }
 }
-async function powershell(script) {
-  const { stdout } = await exec('powershell.exe', ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')], { windowsHide: true, timeout: 15000, maxBuffer: 1024 * 1024 });
+export async function powershell(script) {
+  const prefix = '[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false); $ErrorActionPreference = "Stop"; ';
+  const { stdout } = await exec('powershell.exe', ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(prefix + script, 'utf16le').toString('base64')], { windowsHide: true, timeout: 15000, maxBuffer: 12 * 1024 * 1024 });
   return JSON.parse(stdout.replace(/^\uFEFF/, '').trim() || 'null');
 }
 export function projectFromCommandLine(command = '') {
@@ -66,6 +67,7 @@ export async function openProject(input, deps = {}) {
       const target = projectFromCommandLine(row.CommandLine);
       if (target && await realpath(target).then(p => p.toLowerCase() === key, () => false)) return await finishOpen({ status: 'already_open', projectPath, editorPath: row.ExecutablePath || '', version, pid: row.ProcessId }, input, deps);
     }
+    if ((Array.isArray(rows) ? rows : [rows]).some(row => row && !projectFromCommandLine(row.CommandLine))) throw Error('An editor has inaccessible project arguments; cannot safely rule out a duplicate launch. Inspect running editor windows.');
     if (Date.now() - (recentLaunches.get(key) ?? 0) < 60000) throw Error('A launch was requested within the last 60 seconds; wait for the editor before retrying.');
     const lock = await stat(path.join(projectPath, 'Temp/UnityLockfile')).catch(e => { if (e.code !== 'ENOENT') throw e; });
     if (lock) throw Error('UnityLockfile exists but no matching editor could be confirmed. Refusing duplicate launch; check the editor/lock manually.');

package/lib/project.mjs

@@ -36,13 +36,16 @@ export async function manageProject(input, target = {}, deps = {}) {
     const inventory = await listProjects(target, deps);
     if (inventory.truncated) throw Error('Editor inventory exceeds 100 processes; status cannot safely select a project.');
     const matches = inventory.projects.filter(p => p.projectPath.toLowerCase() === root.toLowerCase());
-    if (!matches.length) return { status: 'not_running', projectPath: root, editorReady: false, connection: target, message: 'No matching editor process found; MCP connectivity is not verified.' };
+    if (!matches.length) {
+      const unknown = inventory.projects.some(p => p.state === 'project_unknown');
+      return { status: unknown ? 'process_unconfirmed' : 'not_running', projectPath: root, running: unknown ? null : false, editorReady: unknown ? null : false, connection: target, message: unknown ? 'Some editor process arguments are unavailable. Cannot confirm whether this project is running; do not launch a duplicate.' : 'No matching editor process found; MCP connectivity is not verified.' };
+    }
     if (matches.length !== 1) throw Error('Multiple editor processes match this project. Resolve duplicates before acting.');
     try {
       await (deps.request ?? requestProject)({ ...input, timeoutMs: input.timeoutMs ?? 10000 }, 'ready', deps);
       return { ...matches[0], state: 'editor_ready', status: 'editor_ready', editorReady: true, connection: target, message: 'Editor readiness confirmed; MCP connectivity is not verified.' };
     } catch (error) {
-      return { ...matches[0], status: 'readiness_unconfirmed', editorReady: false, connection: target, message: error.message };
+      return { ...matches[0], status: 'readiness_unconfirmed', running: true, editorReady: null, connection: target, message: 'Editor process is running; readiness is unknown, not proof of loading. ' + error.message };
     }
   }
   throw Error('Unknown project action.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-unity-mcp",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Unity and Tuanjie editor tools for DSH, powered by CoderGamester/mcp-unity with per-agent lazy loading.",
   "type": "module",
   "license": "MIT",
@@ -39,7 +39,7 @@
     }
   },
   "scripts": {
-    "check": "node --check index.mjs && node --check lib/project.mjs && node --check lib/connection.mjs && node --check lib/engine-tools.mjs && node --check lib/lazy-tools.mjs && node --check lib/configure-project.mjs && node --check lib/open-project.mjs && node --check lib/project-lifecycle.mjs && node --check lib/install-codergamester.mjs",
+    "check": "node --check index.mjs && node --check lib/capture-window.mjs && node --check lib/project.mjs && node --check lib/connection.mjs && node --check lib/engine-tools.mjs && node --check lib/lazy-tools.mjs && node --check lib/configure-project.mjs && node --check lib/open-project.mjs && node --check lib/project-lifecycle.mjs && node --check lib/install-codergamester.mjs",
     "test": "node --test test/*.test.mjs",
     "build": "npm run check",
     "pack:check": "npm pack --dry-run --json"