easytouch-windows 2.0.3 → 2.0.5

package/README.md

@@ -7,7 +7,6 @@
 目前支持以下操作系统的 x64 和 ARM64 两种 CPU 架构：
 
 - [x] Windows
-
 - [x] Linux
 - [x] MACOS（目前缺少设备验证功能）
 
@@ -35,34 +34,40 @@
 
 ### 安装
 
-推荐安装带自动平台选择能力的启动包；如果你只想安装当前系统，也可以直接安装对应平台包：
+推荐安装带初始化 helper 的聚合包；如果你只想安装当前系统，也可以直接安装对应平台包：
 
 ```bash
-# 推荐：自动匹配当前平台
+# 推荐：聚合包，执行 easytouch init 生成 et
 npm i -g @whuanle/easytouch
 
-# Windows
+# 只安装当前系统的平台包
 npm i -g easytouch-windows
-
-# Linux
 npm i -g easytouch-linux
-
-# macOS
 npm i -g easytouch-macos
 ```
 
+`@whuanle/easytouch` 会在包内直接附带 Windows、Linux、macOS 的 x64 和 arm64 原生二进制。执行 `easytouch init` 后，会按当前主机平台和 CPU 架构复制出真正可直接调用的 `et` 文件。
 
+初始化命令：
 
-`@whuanle/easytouch` 会在当前主机上调用对应的平台包；平台包内部同时包含 x64 和 arm64 二进制，安装后会根据当前 CPU 架构自动选择对应程序文件。
+```bash
+# 聚合包
+easytouch init
 
-如果是 Windows，安装后在 `AppData/Roaming/npm` 目录会发现名为 `et` 的文件。
+# 只安装当前系统的平台包时
+easytouch-windows init
+easytouch-linux init
+easytouch-macos init
+```
 
-![image-20260405194137861](images/image-20260405194137861.png)
+`init` 默认会把原生文件写回安装包目录，并同步刷新 `et` 命令入口。
 
 
 
 ### 使用示例
 
+以下示例假设你已经通过 `init` 生成好了原生 `et`：
+
 截取屏幕。
 
 ```
@@ -107,99 +112,56 @@ npx skills add https://github.com/whuanle/EasyTouch
 
 
 
-**本地安装后（推荐）**
+**全局安装后（推荐）**
 
-先执行：
+如果你已经全局安装了聚合包，可以直接使用 helper 命令生成原生 `et`：
 
 ```bash
-npm i @whuanle/easytouch
-npx @whuanle/easytouch init
-```
-
-如果安装的是 `@whuanle/easytouch`，这一步会先自动安装当前系统对应的平台包，再复制出原生 `et` 文件。
-
-如果你已经在项目里安装了依赖，也可以直接执行 `node ./node_modules/@whuanle/easytouch/init.js`，但这只适用于本地安装目录。
-
-执行后会生成：
-
-- Windows：`./node_modules/@whuanle/easytouch/et.exe`
-- Linux / macOS：`./node_modules/@whuanle/easytouch/et`
-
-然后在 MCP 配置里直接指向这个原生文件：
-
-```json
-{
-  "mcpServers": {
-    "easytouch": {
-      "command": "<你的项目路径>/node_modules/@whuanle/easytouch/et",
-      "args": ["mcp-stdio"]
-    }
-  }
-}
+npm i -g @whuanle/easytouch
+easytouch init
 ```
 
-> Windows 请把文件名写成 `et.exe`。Linux / macOS 写 `et`。
+默认会把 `et` 生成到全局安装目录下的包目录里，并同步刷新全局 `et` 命令。
 
-**全局安装后**
+默认路径通常是：
 
-如果你已经全局安装并且宿主能正确处理 PATH，也仍然可以直接使用全局 `et`。首次运行时，如果平台包还没装好，启动器也会自动补装当前平台包：
+- Windows：`<npm root -g>/@whuanle/easytouch/et.exe`
+- Linux / macOS：`<npm root -g>/@whuanle/easytouch/et`
 
-```bash
-npm i -g @whuanle/easytouch
-et init
-```
+全局命令入口通常是：
 
-生成完原生文件后，MCP 仍然可以直接使用全局 `et`：
+- Windows：`<npm prefix -g>/et.cmd`
+- Linux / macOS：`<npm prefix -g>/bin/et`
 
-```json
-{
-  "mcpServers": {
-    "easytouch": {
-      "command": "et",
-      "args": ["mcp-stdio"]
-    }
-  }
-}
-```
-
-如果你只是想手工执行脚本而不走 `et init`，需要先找到全局安装目录，例如：
+如果需要查看你自己机器上的真实路径，可以执行：
 
 ```bash
 npm root -g
+npm prefix -g
 ```
 
-然后再执行对应路径下的 `init.js`，而不是 `./node_modules/...`：
+也可以显式指定输出位置：
 
 ```bash
-node <全局安装目录>/@whuanle/easytouch/init.js
+easytouch init --output <你想放置 et 的路径>
 ```
 
-**宿主程序不走 PATH 时（旧方式）**
-
-- Windows：把 `command` 改成 `C:\\Users\\<你自己的用户名>\\AppData\\Roaming\\npm\\et.cmd`
-- Linux / macOS：先执行 `npm prefix -g`，然后把 `command` 改成 `<prefix>/bin/et`
+如果你安装的是平台包，初始化命令分别是 `easytouch-windows init`、`easytouch-linux init`、`easytouch-macos init`。
 
-**不想初始化原生文件时（备用）**
-
-如果你不想先执行 `init.js`，也可以临时通过 `npx` 启动。这里同样建议统一使用 `@whuanle/easytouch`，不要再按平台分别写包名。首次运行可能会多花一点时间，因为会自动安装当前平台包。
-
-- Windows：`command` 推荐写 `npx.cmd`
-- Linux / macOS：`command` 写 `npx`
+生成完原生文件后，MCP 直接调用这个文件即可：
 
 ```json
 {
   "mcpServers": {
     "easytouch": {
-      "command": "npx.cmd",
-      "args": ["-y", "@whuanle/easytouch", "mcp-stdio"]
+      "command": "et",
+      "args": ["mcp-stdio"]
     }
   }
 }
 ```
 
-> 如果是在 Windows 的 GUI 程序中配置 MCP，直接用 `init.js` 生成的 `et.exe` 最稳。只有在走 `npx` 或全局 npm 命令时，才需要关心 `npx.cmd`、`et.cmd` 这些桥接文件；常见失败表现就是 `LOCAL_PROCESS_ERROR`。
-
-Linux / macOS 如果使用这段备用配置，把 `command` 改回 `npx` 即可。
+如果宿主程序不走 PATH，再改成 `npm prefix -g` 或 `npm root -g` 对应的实际路径。
 
 ### 语义元素定位
 

package/SKILL.md

@@ -364,21 +364,23 @@ et mcp-stdio --output json
 
 ### 配置示例
 
-优先在安装后执行包内 `init.js`，把真实原生 `et` 程序复制出来，再让 MCP 直接调用这个文件：
+优先在全局安装后执行 `init`，把真实原生 `et` 程序复制出来，再让 MCP 直接调用这个文件：
 
 ```bash
-npm i @whuanle/easytouch
-npx @whuanle/easytouch init
+npm i -g @whuanle/easytouch
+easytouch init
 ```
 
-如果安装的是 `@whuanle/easytouch`，这一步会先自动安装当前系统对应的平台包，再生成原生 `et` 文件。
-
-如果依赖已经装在当前项目里，也可以直接执行 `node ./node_modules/@whuanle/easytouch/init.js`，但这只适用于本地安装目录。
+这一步会直接从包内复制当前主机对应的原生 `et` 文件。
 
 生成后的默认路径：
 
-- Windows：`./node_modules/@whuanle/easytouch/et.exe`
-- Linux / macOS：`./node_modules/@whuanle/easytouch/et`
+- Windows：`<npm root -g>/@whuanle/easytouch/et.exe`
+- Linux / macOS：`<npm root -g>/@whuanle/easytouch/et`
+
+同时会刷新全局 `et` 命令。
+
+也可以通过 `--output` 指定输出位置。
 
 推荐配置：
 
@@ -386,7 +388,7 @@ npx @whuanle/easytouch init
 {
   "mcpServers": {
     "easytouch": {
-      "command": "<你的项目路径>/node_modules/@whuanle/easytouch/et",
+      "command": "et",
       "args": ["mcp-stdio"]
     }
   }
@@ -395,39 +397,17 @@ npx @whuanle/easytouch init
 
 Windows 请把文件名写成 `et.exe`。Linux / macOS 写 `et`。
 
-如果是全局安装：
+默认会把 `et` 生成到全局安装目录下的包目录里，并同步刷新全局 `et` 命令。也可以显式指定输出路径：
 
 ```bash
-npm i -g @whuanle/easytouch
-et init
+easytouch init --output <你想放置 et 的路径>
 ```
 
-不要再写成 `node ./node_modules/@whuanle/easytouch/init.js`，因为全局安装不在当前项目目录下。
-
-如果你已经全局安装并且宿主能正确处理 PATH，也可以继续直接调用全局 `et`。首次运行时，如果平台包缺失，启动器也会自动安装当前平台包。
-
-如果宿主程序不能从 PATH 找到命令，旧方式仍可用：
-
-- Windows：把 `command` 改成 `C:\Users\<你自己的用户名>\AppData\Roaming\npm\et.cmd`
-- Linux / macOS：先执行 `npm prefix -g`，再把 `command` 改成 `<prefix>/bin/et`
-
-如果不想执行 `init.js`，也可以临时通过 `npx` 启动。首次运行可能会稍慢，因为会自动安装当前平台包：
+如果你直接安装的是平台包，初始化命令分别是 `easytouch-windows init`、`easytouch-linux init`、`easytouch-macos init`。
 
-- Windows：`command` 推荐写 `npx.cmd`
-- Linux / macOS：`command` 写 `npx`
-
-```json
-{
-  "mcpServers": {
-    "easytouch": {
-      "command": "npx.cmd",
-      "args": ["-y", "@whuanle/easytouch", "mcp-stdio"]
-    }
-  }
-}
-```
+如果需要查看实际路径，可以执行 `npm root -g` 和 `npm prefix -g`。
 
-Linux / macOS 如果使用这段备用配置，把 `command` 改回 `npx` 即可。
+如果宿主能正确处理 PATH，MCP 直接写 `command: "et"` 即可；否则改成 `npm prefix -g` 或 `npm root -g` 对应的实际路径。
 
 如果 Windows 宿主报 `LOCAL_PROCESS_ERROR`，优先改用 `init.js` 生成的 `et.exe`；如果仍走 npm 命令，再检查这里是不是还写成了 `npx`。
 

package/init.js

@@ -3,19 +3,23 @@
 const fs = require("node:fs");
 const path = require("node:path");
 
-const archDirectoryByNodeArch = {
-  x64: "x64",
-  arm64: "arm64",
-};
+const helperCommandName = "easytouch-windows";
+const generatedCommandName = "et";
+
+const supportedArchitectures = new Set(["x64", "arm64"]);
 
 function printUsage() {
   process.stdout.write(
     [
       "Usage:",
-      "  node init.js [--output <path>] [--force]",
+      "  easytouch-windows init [--output <path>] [--force]",
+      "  npx easytouch-windows init [--output <path>] [--force]",
+      "  node init.js [init] [--output <path>] [--force]",
       "",
       "Behavior:",
-      "  Copies the current Windows binary into the package directory as 'et.exe' by default.",
+      "  Copies the current Windows binary out of this package as 'et.exe' by default.",
+      "  By default, writes into this package directory.",
+      "  When installed through npm, also refreshes the 'et' command if possible.",
       "  Use --output to write to a different file or directory.",
     ].join("\n") + "\n"
   );
@@ -26,7 +30,16 @@ function fail(message) {
   process.exit(1);
 }
 
-function parseArgs(argv) {
+function normalizeArgs(argv) {
+  if (argv[0] === "init") {
+    return argv.slice(1);
+  }
+
+  return argv;
+}
+
+function parseArgs(rawArgv) {
+  const argv = normalizeArgs(rawArgv);
   let output = null;
   let force = false;
 
@@ -54,11 +67,11 @@ function parseArgs(argv) {
   return { output, force };
 }
 
-function getAvailableArchitectures() {
+function getAvailableBinaries() {
   try {
     return fs
       .readdirSync(path.join(__dirname, "bin"), { withFileTypes: true })
-      .filter((entry) => entry.isDirectory())
+      .filter((entry) => entry.isFile() && entry.name.startsWith("et_"))
       .map((entry) => entry.name)
       .sort();
   } catch {
@@ -66,28 +79,36 @@ function getAvailableArchitectures() {
   }
 }
 
-function resolveBinaryPath() {
-  const archDirectory = archDirectoryByNodeArch[process.arch];
-  if (!archDirectory) {
-    fail(`Unsupported architecture '${process.arch}' on platform '${process.platform}'.`);
+function binaryNameForArch(arch = process.arch) {
+  if (!supportedArchitectures.has(arch)) {
+    fail(`Unsupported architecture '${arch}' on platform '${process.platform}'.`);
   }
 
-  const sourcePath = path.join(__dirname, "bin", archDirectory, "et.exe");
+  return `et_${arch}.exe`;
+}
+
+function resolveBinaryPath() {
+  const fileName = binaryNameForArch();
+  const sourcePath = path.join(__dirname, "bin", fileName);
   if (!fs.existsSync(sourcePath)) {
-    const availableArchitectures = getAvailableArchitectures();
-    const availableMessage = availableArchitectures.length
-      ? ` Available architectures: ${availableArchitectures.join(", ")}.`
+    const availableBinaries = getAvailableBinaries();
+    const availableMessage = availableBinaries.length
+      ? ` Available binaries: ${availableBinaries.join(", ")}.`
       : "";
-    fail(`The package is missing 'et.exe' for architecture '${archDirectory}'.${availableMessage}`);
+    fail(`The package is missing '${fileName}' for architecture '${process.arch}'.${availableMessage}`);
   }
 
   return sourcePath;
 }
 
+function defaultOutputPath() {
+  return path.join(__dirname, "et.exe");
+}
+
 function resolveOutputPath(requestedOutput) {
   let outputPath = requestedOutput
     ? path.resolve(process.cwd(), requestedOutput)
-    : path.join(__dirname, "et.exe");
+    : defaultOutputPath();
 
   if (fs.existsSync(outputPath)) {
     const stat = fs.statSync(outputPath);
@@ -103,6 +124,22 @@ function resolveOutputPath(requestedOutput) {
   return outputPath;
 }
 
+function filesAreIdentical(leftPath, rightPath) {
+  try {
+    const leftStat = fs.statSync(leftPath);
+    const rightStat = fs.statSync(rightPath);
+    if (leftStat.size !== rightStat.size) {
+      return false;
+    }
+
+    const leftContent = fs.readFileSync(leftPath);
+    const rightContent = fs.readFileSync(rightPath);
+    return leftContent.equals(rightContent);
+  } catch {
+    return false;
+  }
+}
+
 function initializeBinary(sourcePath, destinationPath, force) {
   const resolvedSource = path.resolve(sourcePath);
   const resolvedDestination = path.resolve(destinationPath);
@@ -111,8 +148,15 @@ function initializeBinary(sourcePath, destinationPath, force) {
     return;
   }
 
-  if (fs.existsSync(resolvedDestination) && !force) {
-    fail(`Destination '${resolvedDestination}' already exists. Use --force to overwrite it.`);
+  if (fs.existsSync(resolvedDestination)) {
+    if (filesAreIdentical(resolvedSource, resolvedDestination)) {
+      process.stdout.write(`et init: binary already available at ${resolvedDestination}\n`);
+      return;
+    }
+
+    if (!force) {
+      fail(`Destination '${resolvedDestination}' already exists. Use --force to overwrite it.`);
+    }
   }
 
   fs.mkdirSync(path.dirname(resolvedDestination), { recursive: true });
@@ -120,5 +164,157 @@ function initializeBinary(sourcePath, destinationPath, force) {
   process.stdout.write(`et init: copied ${resolvedSource} -> ${resolvedDestination}\n`);
 }
 
+function findNodeModulesRoot(startDir) {
+  let current = path.resolve(startDir);
+
+  while (true) {
+    if (path.basename(current) === "node_modules") {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+function commandFileCandidates(commandName) {
+  return [`${commandName}.cmd`, `${commandName}.ps1`, commandName];
+}
+
+function uniquePaths(paths) {
+  return [...new Set(paths.filter(Boolean).map((entry) => path.resolve(entry)))];
+}
+
+function resolveCommandBinDir(startDir, commandName) {
+  const nodeModulesRoot = findNodeModulesRoot(startDir);
+  if (!nodeModulesRoot) {
+    return null;
+  }
+
+  const installRoot = path.dirname(nodeModulesRoot);
+  const candidates = uniquePaths([path.join(nodeModulesRoot, ".bin"), installRoot]);
+
+  for (const candidate of candidates) {
+    for (const fileName of commandFileCandidates(commandName)) {
+      if (fs.existsSync(path.join(candidate, fileName))) {
+        return candidate;
+      }
+    }
+  }
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function managedCommandMarker() {
+  return "EasyTouch generated by init";
+}
+
+function readTextFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function assertManagedCommandTarget(filePath, force) {
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+
+  const content = readTextFile(filePath);
+  if (content && content.includes(managedCommandMarker())) {
+    return;
+  }
+
+  if (!force) {
+    fail(`Command '${filePath}' already exists. Use --force to overwrite it.`);
+  }
+}
+
+function writeManagedCommand(filePath, content, force, executable) {
+  assertManagedCommandTarget(filePath, force);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, "utf8");
+  if (executable) {
+    fs.chmodSync(filePath, 0o755);
+  }
+}
+
+function escapeForSingleQuotedPowerShell(value) {
+  return value.replace(/'/g, "''");
+}
+
+function relativeShellPath(fromDir, toFile) {
+  return path.relative(fromDir, toFile).split(path.sep).join("/");
+}
+
+function installGeneratedCommand(targetBinaryPath, force) {
+  const binDir = resolveCommandBinDir(__dirname, helperCommandName);
+  if (!binDir) {
+    return;
+  }
+
+  const resolvedTarget = path.resolve(targetBinaryPath);
+  const relativeWindowsPath = path.relative(binDir, resolvedTarget);
+  const relativePosixPath = relativeShellPath(binDir, resolvedTarget);
+
+  writeManagedCommand(
+    path.join(binDir, generatedCommandName),
+    [
+      "#!/bin/sh",
+      `# ${managedCommandMarker()}`,
+      'basedir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)',
+      `exec "$basedir/${relativePosixPath}" "$@"`,
+      "",
+    ].join("\n"),
+    force,
+    true
+  );
+
+  writeManagedCommand(
+    path.join(binDir, `${generatedCommandName}.cmd`),
+    [
+      "@ECHO off",
+      `:: ${managedCommandMarker()}`,
+      "SETLOCAL",
+      `SET \"_ET_TARGET=%~dp0${relativeWindowsPath}\"`,
+      '"%_ET_TARGET%" %*',
+      "",
+    ].join("\r\n"),
+    force,
+    false
+  );
+
+  writeManagedCommand(
+    path.join(binDir, `${generatedCommandName}.ps1`),
+    [
+      `# ${managedCommandMarker()}`,
+      `$target = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot '${escapeForSingleQuotedPowerShell(relativeWindowsPath)}'))`,
+      "& $target @args",
+      "exit $LASTEXITCODE",
+      "",
+    ].join("\r\n"),
+    force,
+    false
+  );
+
+  process.stdout.write(`et init: updated command '${generatedCommandName}' in ${binDir}\n`);
+}
+
 const options = parseArgs(process.argv.slice(2));
-initializeBinary(resolveBinaryPath(), resolveOutputPath(options.output), options.force);
+const outputPath = resolveOutputPath(options.output);
+initializeBinary(resolveBinaryPath(), outputPath, options.force);
+
+if (path.resolve(outputPath) === path.resolve(defaultOutputPath())) {
+  installGeneratedCommand(outputPath, options.force);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "easytouch-windows",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Windows binary distribution for EasyTouch with x64 and arm64 binaries.",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "commonjs",
@@ -13,7 +13,9 @@
   },
   "homepage": "https://github.com/whuanle/EasyTouch#readme",
   "bin": {
-    "et": "bin/et.js"
+    "easytouch-windows": "init.js",
+    "et_x64": "bin/et_x64.exe",
+    "et_arm64": "bin/et_arm64.exe"
   },
   "os": [
     "win32"

package/bin/et.js

@@ -1,60 +0,0 @@
-#!/usr/bin/env node
-
-const cp = require("node:child_process");
-const fs = require("node:fs");
-const path = require("node:path");
-
-const archDirectoryByNodeArch = {
-  x64: "x64",
-  arm64: "arm64",
-};
-
-const packageName = require(path.join(__dirname, "..", "package.json")).name;
-
-function fail(message) {
-  process.stderr.write(`et: ${message}\n`);
-  process.exit(1);
-}
-
-function getAvailableArchitectures() {
-  try {
-    return fs
-      .readdirSync(__dirname, { withFileTypes: true })
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => entry.name)
-      .sort();
-  } catch {
-    return [];
-  }
-}
-
-function resolveBinaryPath() {
-  const archDirectory = archDirectoryByNodeArch[process.arch];
-  if (!archDirectory) {
-    fail(`Unsupported architecture '${process.arch}' on platform '${process.platform}'.`);
-  }
-
-  const binaryName = process.platform === "win32" ? "et.exe" : "et";
-  const binaryPath = path.join(__dirname, archDirectory, binaryName);
-  if (!fs.existsSync(binaryPath)) {
-    const availableArchitectures = getAvailableArchitectures();
-    const availableMessage = availableArchitectures.length
-      ? ` Available architectures: ${availableArchitectures.join(", ")}.`
-      : "";
-    fail(
-      `The platform package '${packageName}' is missing '${binaryName}' for architecture '${archDirectory}'.${availableMessage}`
-    );
-  }
-
-  return binaryPath;
-}
-
-const result = cp.spawnSync(resolveBinaryPath(), process.argv.slice(2), {
-  stdio: "inherit",
-});
-
-if (result.error) {
-  fail(result.error.message);
-}
-
-process.exit(result.status ?? 1);