dsh-unity-mcp 0.0.8 → 0.0.10

package/README.md

@@ -17,7 +17,7 @@
 需要 Node.js 22+、DSH `>=0.2.1-rc.3 <0.3.0`。在 DSH 插件管理中安装：
 
 ```text
-dsh-unity-mcp
+dsh-unity-mcp@0.0.10
 ```
 
 本地工程管理目前只支持 Windows。上游声明 Unity 2022.3+；本插件已在独立团结工程中验证，但不能保证所有 Unity / Tuanjie 版本都兼容。
@@ -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`。
@@ -109,3 +110,9 @@ npm run pack:check
 测试覆盖服务器发现、配置边界、就绪等待、安装保护、保存关闭和 Agent 隔离。上下文大小测试比较 UTF-8 schema 字节数，不把字节数当作模型 token 数。
 
 本适配插件采用 MIT 许可证。上游 [CoderGamester/mcp-unity](https://github.com/CoderGamester/mcp-unity) 也采用 MIT 许可证；本包不分发上游引擎或服务器源码。图标由 Krea 2 Turbo 生成，不使用 Unity 官方标志。许可与素材说明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
+
+## 按需技能目录
+
+- [unity-safe-verification](skills/unity-safe-verification/SKILL.md)：安全操作、回读和 Play 验收。
+
+这些技能随 npm 包分发，由插件启用时注册，禁用或卸载时撤销；正文仍按需加载，资源路径指向包内目录。无需另建用户级副本或目录联接。旧版已有的同名本地入口应核对来源后移到技能扫描范围之外备份，不删除技能正文。独立用户技能不会被插件改写或删除；同名条目遵循宿主优先级，禁用插件后用户条目仍可使用。跨插件技能引用需要启用对应插件。

package/index.mjs

@@ -4,9 +4,11 @@ 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';
+import { installPackagedSkills } from './lib/packaged-skills.mjs';
 export const name = 'dsh-unity-mcp';
-export const inject = ['tools', 'agents', 'configEditor'];
+export const inject = ['tools', 'agents', 'configEditor', 'attachments', 'skills'];
 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'),
@@ -17,8 +19,9 @@ export const Config = z.object({
   toolCallTimeoutMs: z.number().min(1000).max(600000).step(1).default(120000).description('工具超时（毫秒） / Tool timeout (ms)')
 });
 export async function apply(ctx, config) {
+  installPackagedSkills(ctx, new URL('./skills/', import.meta.url));
   // 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/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/packaged-skills.mjs

@@ -0,0 +1,27 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export function readPackagedSkills(directory) {
+  return readdirSync(directory, { withFileTypes: true })
+    .filter(entry => entry.isDirectory()).map(entry => entry.name).sort().map(name => {
+      const base = new URL(`${name}/`, directory);
+      const path = new URL('SKILL.md', base);
+      const source = readFileSync(path, 'utf8');
+      const match = /^---\r?\nname: ([^\r\n]+)\r?\ndescription: ([^\r\n]+)\r?\n---\r?\n([\s\S]*)$/u.exec(source);
+      if (!match || match[1] !== name || !match[2].trim()) {
+        throw new Error(`Invalid packaged skill frontmatter: ${name}`);
+      }
+      return {
+        name, description: match[2], content: match[3], source: 'runtime',
+        path: fileURLToPath(path),
+        resourceBase: { kind: 'directory', path: fileURLToPath(base) },
+        invocation: { modelInvocable: true, userInvocable: true },
+      };
+    });
+}
+
+export function installPackagedSkills(ctx, directory) {
+  // Validate all plain name/description frontmatter before registering any entry.
+  const skills = readPackagedSkills(directory);
+  for (const skill of skills) ctx.effect(() => ctx.skills.register(skill));
+}

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.8",
+  "version": "0.0.10",
   "description": "Unity and Tuanjie editor tools for DSH, powered by CoderGamester/mcp-unity with per-agent lazy loading.",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,7 @@
     "./locale/*.json": "./locale/*.json"
   },
   "files": [
+    "skills",
     "index.mjs",
     "lib",
     "engine",
@@ -39,7 +40,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 && node --check lib/packaged-skills.mjs",
     "test": "node --test test/*.test.mjs",
     "build": "npm run check",
     "pack:check": "npm pack --dry-run --json"

package/skills/unity-safe-verification/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: unity-safe-verification
+description: 操作 Unity 或团结工程、修改场景资产或交付可玩版本时使用；确认工程就绪、回读目标并在 Play 中验收。
+---
+
+# Unity／团结安全操作与实机验收
+
+## 确认目标
+
+加载当前工具目录，枚举工程后固定绝对路径。分别确认编辑器就绪、MCP 连接、场景和 Play／Prefab 状态。进程、目录、握手只证明各自一层；只读场景查询需与工程一致。超时不重复启动或切换全局连接。
+
+## 修改前
+
+读取目标、受影响场景、Prefab、共享材质和引用，记录定位与原值，不按脚本类名猜对象名。明确世界／本地坐标、共享／实例资源、活动场景／另存目标。参数与枚举按当前 schema 核验。
+
+保存用户修改后再复制工程，磁盘副本不包含未保存状态。安装包、升级编辑器、切换连接、打开不可信项目均在授权范围内处理。
+
+## 写后回读
+
+小范围写入后查询对象实际值、组件、引用并检查控制台。回执不保证最终值；部分修改可能已发生，批量回滚按实际契约判断。修改共享资源前核对其他引用。超时先查状态，特别是播放切换、删除与父级变更。
+
+## 分层验收
+
+1. 文件：diff、资产与 meta 配对及引用；哈希只证明字节。
+2. 导入编译：等待完成，读取相关堆栈，不清日志掩盖错误。
+3. 场景：加载明确场景，核对层级和画面；默认空场景不证明工程损坏。
+4. Play：按需求走主路径及失败分支，检查输入、状态、真实画面和运行错误。静态测试不代替游玩。
+5. 持久化：退出 Play，确认编辑态结果并保存具名场景及资源，核对磁盘；运行态修改可能被丢弃。
+
+测试使用隔离对象或夹具，只清理自己的对象。报告各层验证范围；不能进入 Play 就列出未验证功能。
+
+例：位置修改后读取 Transform，再在目标场景检查落脚点；编译通过不证明角色没有悬空。