@hermespilot/link 0.5.1 → 0.5.3

package/dist/cli/index.js

@@ -14,6 +14,7 @@ import {
   ensureHermesApiServerAvailable,
   ensureHermesApiServerConfig,
   ensureIdentity,
+  fetchRelayStreamBatchPolicy,
   getDaemonStatus,
   getIdentityStatus,
   getLinkLogFile,
@@ -36,12 +37,12 @@ import {
   startDaemonProcess,
   startLinkService,
   stopDaemonProcess
-} from "../chunk-PULX22HX.js";
+} from "../chunk-5JBXQ3VC.js";
 
 // src/cli/index.ts
 import { Command } from "commander";
-import { realpathSync } from "fs";
-import path3 from "path";
+import { realpathSync as realpathSync2 } from "fs";
+import path4 from "path";
 import { createInterface } from "readline/promises";
 import { pathToFileURL } from "url";
 import qrcode from "qrcode-terminal";
@@ -139,6 +140,7 @@ async function hasSystemctlUser() {
 }
 function launchdDefinition() {
   const filePath = path.join(os.homedir(), "Library", "LaunchAgents", `${MACOS_LABEL}.plist`);
+  const environment = autostartEnvironment();
   return {
     method: "launchd",
     filePath,
@@ -154,6 +156,10 @@ function launchdDefinition() {
     <string>${xmlEscape(currentCliScriptPath())}</string>
     <string>daemon-supervisor</string>
   </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${plistEnvironmentEntries(environment)}
+  </dict>
   <key>RunAtLoad</key>
   <true/>
   <key>KeepAlive</key>
@@ -165,6 +171,7 @@ function launchdDefinition() {
 }
 function systemdUserDefinition() {
   const filePath = path.join(os.homedir(), ".config", "systemd", "user", "hermeslink.service");
+  const environment = autostartEnvironment();
   return {
     method: "systemd-user",
     filePath,
@@ -174,6 +181,7 @@ After=network-online.target
 
 [Service]
 Type=simple
+${systemdEnvironmentLines(environment)}
 ExecStart=${systemdQuote(process.execPath)} ${systemdQuote(currentCliScriptPath())} daemon-supervisor
 Restart=no
 
@@ -184,13 +192,14 @@ WantedBy=default.target
 }
 function xdgAutostartDefinition() {
   const filePath = path.join(os.homedir(), ".config", "autostart", "hermeslink.desktop");
+  const environment = autostartEnvironment();
   return {
     method: "xdg-autostart",
     filePath,
     content: `[Desktop Entry]
 Type=Application
 Name=Hermes Link
-Exec=${desktopQuote(process.execPath)} ${desktopQuote(currentCliScriptPath())} daemon-supervisor
+Exec=${desktopQuote("/usr/bin/env")} ${desktopEnvironmentArgs(environment)} ${desktopQuote(process.execPath)} ${desktopQuote(currentCliScriptPath())} daemon-supervisor
 Terminal=false
 X-GNOME-Autostart-enabled=true
 `
@@ -199,12 +208,16 @@ X-GNOME-Autostart-enabled=true
 function windowsStartupDefinition() {
   const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
   const filePath = path.join(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Startup", "HermesLink.cmd");
+  const environment = autostartEnvironment();
   return {
     method: "windows-startup",
     filePath,
-    content: `@echo off\r
-start "" /min "${process.execPath}" "${currentCliScriptPath()}" daemon-supervisor\r
-`
+    content: [
+      "@echo off",
+      ...cmdEnvironmentLines(environment),
+      `start "" /min "${process.execPath}" "${currentCliScriptPath()}" daemon-supervisor`,
+      ""
+    ].join("\r\n")
   };
 }
 function unsupportedStatus() {
@@ -224,6 +237,57 @@ function systemdQuote(value) {
 function desktopQuote(value) {
   return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
 }
+function autostartEnvironment() {
+  const environment = {};
+  const pathValue = buildAutostartPath();
+  if (pathValue) {
+    environment.PATH = pathValue;
+  }
+  const hermesBin = process.env.HERMES_BIN?.trim();
+  if (hermesBin) {
+    environment.HERMES_BIN = hermesBin;
+  }
+  return environment;
+}
+function buildAutostartPath() {
+  const separator = process.platform === "win32" ? ";" : ":";
+  const candidates = [
+    path.dirname(process.execPath),
+    ...(process.env.PATH ?? "").split(separator),
+    path.join(os.homedir(), ".local", "bin"),
+    ...process.platform === "win32" ? [] : ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"]
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  const entries = [];
+  for (const candidate of candidates) {
+    const normalized = candidate.trim();
+    if (!normalized) {
+      continue;
+    }
+    const key = process.platform === "win32" ? normalized.toLowerCase() : normalized;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    entries.push(normalized);
+  }
+  return entries.join(separator);
+}
+function plistEnvironmentEntries(environment) {
+  return Object.entries(environment).map(([key, value]) => `    <key>${xmlEscape(key)}</key>
+    <string>${xmlEscape(value)}</string>`).join("\n");
+}
+function systemdEnvironmentLines(environment) {
+  return Object.entries(environment).map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}`).join("\n");
+}
+function desktopEnvironmentArgs(environment) {
+  return Object.entries(environment).map(([key, value]) => desktopQuote(`${key}=${value}`)).join(" ");
+}
+function cmdEnvironmentLines(environment) {
+  return Object.entries(environment).map(
+    ([key, value]) => `set "${key}=${value.replaceAll('"', "")}"`
+  );
+}
 
 // src/i18n.ts
 var messages = {
@@ -303,6 +367,25 @@ var messages = {
     "pair.autostartUnchanged": "Existing paired devices found. Boot autostart settings were left unchanged.",
     "pair.autostartFailed": "Pairing succeeded, but boot autostart could not be enabled: {message}",
     "doctor.description": "Run local diagnostics",
+    "doctor.installOnly": "only check npm global command and PATH setup",
+    "doctor.installHeader": "Install/PATH diagnostics:",
+    "doctor.installNpmPrefix": "npm global prefix: {value}",
+    "doctor.installGlobalBin": "npm global bin directory: {value}",
+    "doctor.installExpectedCommand": "expected hermeslink command: {value} ({state})",
+    "doctor.installCommandOnPath": "hermeslink found on PATH: {value}",
+    "doctor.installUnknown": "unknown",
+    "doctor.installOk": "ok",
+    "doctor.installMissing": "missing",
+    "doctor.installReady": "The global hermeslink command is visible to this shell.",
+    "doctor.installPrefixUnavailable": "Could not read npm global prefix with `{command} prefix -g`. Check that npm is available in this shell.",
+    "doctor.installExpectedMissing": "npm does not appear to have created the global hermeslink shim. Re-run `npm install -g @hermespilot/link` in the same system environment where Hermes runs.",
+    "doctor.installPathMissing": "npm installed hermeslink, but this shell cannot see npm's global bin directory on PATH.",
+    "doctor.installShadowed": "A different hermeslink command appears earlier on PATH. Remove the old command or move npm's global bin directory earlier on PATH.",
+    "doctor.installWslWindowsNpm": "This looks like Windows Node/npm being used from WSL (`/mnt/c/...`). Prefer installing Linux Node.js inside WSL, or run both Hermes Agent and Hermes Link on the Windows host.",
+    "doctor.installDirectRun": "Direct run without changing PATH: {command}",
+    "doctor.installUnixPathHint": 'Temporary PATH fix: export PATH="{path}:$PATH"',
+    "doctor.installWindowsPathHint": "Add this directory to your user Path, then open a new terminal: {path}",
+    "doctor.installNpxFallback": "PATH-independent fallback: npx --yes @hermespilot/link doctor --install",
     "doctor.identityOk": "Runtime identity: OK",
     "doctor.installId": "Install ID: {value}",
     "doctor.linkId": "Link ID: {value}",
@@ -401,6 +484,25 @@ var messages = {
     "pair.autostartUnchanged": "\u68C0\u6D4B\u5230\u5DF2\u6709\u914D\u5BF9\u8BBE\u5907\uFF0C\u5F00\u673A\u81EA\u542F\u8BBE\u7F6E\u4FDD\u6301\u4E0D\u53D8\u3002",
     "pair.autostartFailed": "\u914D\u5BF9\u5DF2\u6210\u529F\uFF0C\u4F46\u542F\u7528\u5F00\u673A\u81EA\u542F\u5931\u8D25\uFF1A{message}",
     "doctor.description": "\u8FD0\u884C\u672C\u673A\u8BCA\u65AD",
+    "doctor.installOnly": "\u53EA\u68C0\u67E5 npm \u5168\u5C40\u547D\u4EE4\u548C PATH \u8BBE\u7F6E",
+    "doctor.installHeader": "\u5B89\u88C5 / PATH \u8BCA\u65AD\uFF1A",
+    "doctor.installNpmPrefix": "npm \u5168\u5C40 prefix\uFF1A{value}",
+    "doctor.installGlobalBin": "npm \u5168\u5C40 bin \u76EE\u5F55\uFF1A{value}",
+    "doctor.installExpectedCommand": "\u9884\u671F\u7684 hermeslink \u547D\u4EE4\uFF1A{value}\uFF08{state}\uFF09",
+    "doctor.installCommandOnPath": "\u5F53\u524D PATH \u627E\u5230\u7684 hermeslink\uFF1A{value}",
+    "doctor.installUnknown": "\u672A\u77E5",
+    "doctor.installOk": "\u5B58\u5728",
+    "doctor.installMissing": "\u672A\u627E\u5230",
+    "doctor.installReady": "\u5F53\u524D shell \u53EF\u4EE5\u76F4\u63A5\u627E\u5230\u5168\u5C40 hermeslink \u547D\u4EE4\u3002",
+    "doctor.installPrefixUnavailable": "\u65E0\u6CD5\u901A\u8FC7 `{command} prefix -g` \u8BFB\u53D6 npm \u5168\u5C40 prefix\u3002\u8BF7\u5148\u786E\u8BA4\u5F53\u524D shell \u80FD\u8FD0\u884C npm\u3002",
+    "doctor.installExpectedMissing": "npm \u4F3C\u4E4E\u6CA1\u6709\u521B\u5EFA\u5168\u5C40 hermeslink shim\u3002\u8BF7\u5728 Hermes \u6240\u5728\u7684\u540C\u4E00\u7CFB\u7EDF\u73AF\u5883\u91CC\u91CD\u65B0\u6267\u884C `npm install -g @hermespilot/link`\u3002",
+    "doctor.installPathMissing": "npm \u5DF2\u5B89\u88C5 hermeslink\uFF0C\u4F46\u5F53\u524D shell \u7684 PATH \u91CC\u6CA1\u6709 npm \u5168\u5C40 bin \u76EE\u5F55\u3002",
+    "doctor.installShadowed": "PATH \u524D\u9762\u5B58\u5728\u53E6\u4E00\u4E2A hermeslink \u547D\u4EE4\u3002\u8BF7\u5220\u9664\u65E7\u547D\u4EE4\uFF0C\u6216\u628A npm \u5168\u5C40 bin \u76EE\u5F55\u653E\u5230 PATH \u66F4\u524D\u9762\u3002",
+    "doctor.installWslWindowsNpm": "\u5F53\u524D\u770B\u8D77\u6765\u662F\u5728 WSL \u4E2D\u8C03\u7528\u4E86 Windows Node/npm\uFF08`/mnt/c/...`\uFF09\u3002\u5EFA\u8BAE\u5728 WSL \u5185\u5B89\u88C5 Linux \u7248 Node.js\uFF0C\u6216\u628A Hermes Agent \u4E0E Hermes Link \u90FD\u653E\u5728 Windows \u5BBF\u4E3B\u673A\u8FD0\u884C\u3002",
+    "doctor.installDirectRun": "\u4E0D\u6539 PATH \u4E5F\u53EF\u4EE5\u76F4\u63A5\u8FD0\u884C\uFF1A{command}",
+    "doctor.installUnixPathHint": '\u4E34\u65F6\u8865 PATH\uFF1Aexport PATH="{path}:$PATH"',
+    "doctor.installWindowsPathHint": "\u628A\u8FD9\u4E2A\u76EE\u5F55\u52A0\u5165\u5F53\u524D\u7528\u6237\u7684 Path\uFF0C\u7136\u540E\u91CD\u65B0\u6253\u5F00\u7EC8\u7AEF\uFF1A{path}",
+    "doctor.installNpxFallback": "\u4E0D\u4F9D\u8D56 PATH \u7684\u515C\u5E95\u547D\u4EE4\uFF1Anpx --yes @hermespilot/link doctor --install",
     "doctor.identityOk": "\u8FD0\u884C\u8EAB\u4EFD\uFF1A\u6B63\u5E38",
     "doctor.installId": "Install ID\uFF1A{value}",
     "doctor.linkId": "Link ID\uFF1A{value}",
@@ -701,6 +803,135 @@ async function spawnDetached(command, args) {
   });
 }
 
+// src/runtime/install-info.ts
+import { execFileSync } from "child_process";
+import { existsSync, realpathSync } from "fs";
+import path3 from "path";
+function readInstallPathInfo() {
+  return inspectInstallPath({
+    npmPrefix: resolveGlobalPrefix()
+  });
+}
+function inspectInstallPath(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const exists = options.exists ?? existsSync;
+  const realpath = options.realpath ?? realpathSync;
+  const npmPrefix = options.npmPrefix === void 0 ? resolveGlobalPrefix(platform, env) : options.npmPrefix;
+  const globalBinDir = npmPrefix ? resolveGlobalBinDir(npmPrefix, platform) : null;
+  const expectedCommandPath = globalBinDir ? resolveGlobalCommandPath(globalBinDir, platform) : null;
+  const expectedCommandExists = expectedCommandPath ? exists(expectedCommandPath) : false;
+  const pathIncludesGlobalBin = globalBinDir ? pathIncludes(globalBinDir, env.PATH ?? "", platform) : false;
+  const commandOnPath = findCommandOnPath(LINK_COMMAND, env, platform, exists);
+  const commandOnPathMatchesExpected = commandOnPath && expectedCommandPath ? samePath(commandOnPath, expectedCommandPath, platform, realpath) : null;
+  return {
+    platform,
+    npmCommand: resolveNpmCommand(platform),
+    npmPrefix,
+    globalBinDir,
+    expectedCommandPath,
+    expectedCommandExists,
+    pathIncludesGlobalBin,
+    commandOnPath,
+    commandOnPathMatchesExpected,
+    wslWindowsNpmLikely: platform === "linux" && Boolean(npmPrefix?.startsWith("/mnt/c/"))
+  };
+}
+function hasInstallPathIssue(info) {
+  return !info.npmPrefix || !info.globalBinDir || !info.expectedCommandExists || !info.pathIncludesGlobalBin || !info.commandOnPath || info.commandOnPathMatchesExpected === false || info.wslWindowsNpmLikely;
+}
+function resolveGlobalBinDir(prefix, platform) {
+  return platform === "win32" ? prefix : pathForPlatform(platform).join(prefix, "bin");
+}
+function resolveGlobalCommandPath(binDir, platform) {
+  return pathForPlatform(platform).join(
+    binDir,
+    platform === "win32" ? `${LINK_COMMAND}.cmd` : LINK_COMMAND
+  );
+}
+function formatShellCommand(commandPath, args, platform) {
+  return [quoteShellToken(commandPath, platform), ...args.map((arg) => quoteShellToken(arg, platform))].join(" ");
+}
+function resolveGlobalPrefix(platform = process.platform, env = process.env) {
+  const envPrefix = env.npm_config_prefix?.trim() ?? env.npm_config_global_prefix?.trim() ?? "";
+  if (envPrefix) {
+    return envPrefix;
+  }
+  try {
+    const output = execFileSync(resolveNpmCommand(platform), ["prefix", "-g"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2e3
+    });
+    return output.trim() || null;
+  } catch {
+    return null;
+  }
+}
+function resolveNpmCommand(platform) {
+  return platform === "win32" ? "npm.cmd" : "npm";
+}
+function pathIncludes(target, pathValue, platform) {
+  const normalizedTarget = normalizePath(target, platform);
+  return splitPath(pathValue, platform).some(
+    (entry) => normalizePath(entry, platform) === normalizedTarget
+  );
+}
+function findCommandOnPath(command, env, platform, exists) {
+  for (const entry of splitPath(env.PATH ?? "", platform)) {
+    for (const fileName of commandFileNames(command, env, platform)) {
+      const candidate = pathForPlatform(platform).join(entry, fileName);
+      if (exists(candidate)) {
+        return candidate;
+      }
+    }
+  }
+  return null;
+}
+function commandFileNames(command, env, platform) {
+  if (platform !== "win32") {
+    return [command];
+  }
+  const extensions = (env.PATHEXT || ".COM;.EXE;.BAT;.CMD;.PS1").split(";").map((value) => value.trim()).filter(Boolean);
+  return [command, ...extensions.map((extension) => `${command}${extension.toLowerCase()}`)];
+}
+function samePath(left, right, platform, realpath) {
+  try {
+    return normalizeComparablePath(realpath(left), platform) === normalizeComparablePath(realpath(right), platform);
+  } catch {
+    return normalizeComparablePath(left, platform) === normalizeComparablePath(right, platform);
+  }
+}
+function splitPath(pathValue, platform) {
+  const delimiter = platform === "win32" ? ";" : ":";
+  return pathValue.split(delimiter).map((entry) => stripPathQuotes(entry.trim())).filter(Boolean);
+}
+function stripPathQuotes(value) {
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+function normalizePath(value, platform) {
+  return normalizeComparablePath(pathForPlatform(platform).resolve(value), platform);
+}
+function normalizeComparablePath(value, platform) {
+  const normalized = pathForPlatform(platform).normalize(value);
+  return platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function pathForPlatform(platform) {
+  return platform === "win32" ? path3.win32 : path3.posix;
+}
+function quoteShellToken(value, platform) {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/u.test(value)) {
+    return value;
+  }
+  if (platform === "win32") {
+    return `"${value.replaceAll('"', '\\"')}"`;
+  }
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
 // src/cli/index.ts
 var program = new Command();
 var helpLanguage = detectSystemLanguage();
@@ -874,6 +1105,7 @@ program.command("pair").description(helpText("pair.description")).action(async (
   const hadActiveDevices = await hasActiveDevices(paths);
   const probeBeforePair = await probeLocalLinkService({ port: config.port });
   const prepared = await preparePairing(paths);
+  const streamBatchPolicy = await fetchRelayStreamBatchPolicy(config.serverBaseUrl);
   await clearPairingClaim(prepared.sessionId, paths);
   const probe = await probeLocalLinkService({ port: config.port, linkId: prepared.linkId });
   if (probe.reachable && !probe.reusable) {
@@ -892,7 +1124,8 @@ program.command("pair").description(helpText("pair.description")).action(async (
     pairingRelayBridge = connectRelayControl({
       relayBaseUrl: prepared.relayBaseUrl,
       linkId: prepared.linkId,
-      localPort: config.port
+      localPort: config.port,
+      initialStreamBatchPolicy: streamBatchPolicy
     });
     pairingRelayBridge.publishNetworkRoutes(prepared.routes);
   }
@@ -999,7 +1232,17 @@ program.command("logs").description(helpText("logs.description")).action(async (
   console.log(t("logs.servicePath", { path: getLinkLogFile(paths) }));
   console.log(t("logs.daemonPath", { path: daemonLogFile(paths) }));
 });
-program.command("doctor").description(helpText("doctor.description")).action(async () => {
+program.command("doctor").option("--install", helpText("doctor.installOnly")).description(helpText("doctor.description")).action(async (options) => {
+  const installInfo = readInstallPathInfo();
+  const installLanguage = await loadCliLanguage().catch(() => detectSystemLanguage());
+  const installT = translate.bind(null, installLanguage);
+  if (options.install) {
+    printInstallDiagnostics(installInfo, installT, true);
+    return;
+  }
+  if (hasInstallPathIssue(installInfo)) {
+    printInstallDiagnostics(installInfo, installT, false);
+  }
   const [identity, config] = await Promise.all([ensureIdentity(), loadConfig()]);
   const language = resolveLanguage(config.language);
   const t = translate.bind(null, language);
@@ -1045,6 +1288,53 @@ async function loadCliLanguage() {
 function formatHermesVersion(version) {
   return version.version ?? version.raw;
 }
+function printInstallDiagnostics(info, t, verbose) {
+  if (!verbose && !hasInstallPathIssue(info)) {
+    return;
+  }
+  console.log(t("doctor.installHeader"));
+  console.log(t("doctor.installNpmPrefix", { value: info.npmPrefix ?? t("doctor.installUnknown") }));
+  console.log(t("doctor.installGlobalBin", { value: info.globalBinDir ?? t("doctor.installUnknown") }));
+  console.log(
+    t("doctor.installExpectedCommand", {
+      value: info.expectedCommandPath ?? t("doctor.installUnknown"),
+      state: info.expectedCommandExists ? t("doctor.installOk") : t("doctor.installMissing")
+    })
+  );
+  console.log(
+    t("doctor.installCommandOnPath", {
+      value: info.commandOnPath ?? t("doctor.installMissing")
+    })
+  );
+  if (!info.npmPrefix) {
+    console.log(t("doctor.installPrefixUnavailable", { command: info.npmCommand }));
+  } else if (!info.expectedCommandExists) {
+    console.log(t("doctor.installExpectedMissing"));
+  } else if (!info.pathIncludesGlobalBin || !info.commandOnPath) {
+    console.log(t("doctor.installPathMissing"));
+  } else if (info.commandOnPathMatchesExpected === false) {
+    console.log(t("doctor.installShadowed"));
+  } else {
+    console.log(t("doctor.installReady"));
+  }
+  if (info.wslWindowsNpmLikely) {
+    console.log(t("doctor.installWslWindowsNpm"));
+  }
+  if (info.expectedCommandPath && info.expectedCommandExists) {
+    console.log(
+      t("doctor.installDirectRun", {
+        command: formatShellCommand(info.expectedCommandPath, ["doctor"], info.platform)
+      })
+    );
+  }
+  if (info.globalBinDir && info.platform !== "win32") {
+    console.log(t("doctor.installUnixPathHint", { path: info.globalBinDir }));
+  }
+  if (info.globalBinDir && info.platform === "win32") {
+    console.log(t("doctor.installWindowsPathHint", { path: info.globalBinDir }));
+  }
+  console.log(t("doctor.installNpxFallback"));
+}
 function pairingPreflightProgressKey(stage) {
   switch (stage) {
     case "hermes_files":
@@ -1193,9 +1483,9 @@ function isCliEntrypoint(entry = process.argv[1], moduleUrl = import.meta.url) {
     return false;
   }
   try {
-    return moduleUrl === pathToFileURL(realpathSync(path3.resolve(entry))).href;
+    return moduleUrl === pathToFileURL(realpathSync2(path4.resolve(entry))).href;
   } catch {
-    return moduleUrl === pathToFileURL(path3.resolve(entry)).href;
+    return moduleUrl === pathToFileURL(path4.resolve(entry)).href;
   }
 }
 export {

package/dist/http/app.js

@@ -1,6 +1,6 @@
 import {
   createApp
-} from "../chunk-PULX22HX.js";
+} from "../chunk-5JBXQ3VC.js";
 export {
   createApp
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hermespilot/link",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "private": false,
   "description": "Hermes Link companion service and CLI for connecting hermes-agent through HermesPilot",
   "license": "MIT",

package/scripts/postinstall.mjs

@@ -99,9 +99,12 @@ async function main() {
       console.log(
         `如果当前 shell 找不到 \`hermeslink\`，说明 npm 全局 bin 目录没有进 PATH：${globalBinDir}`,
       );
+      console.log("你也可以先运行不依赖 PATH 的诊断：npx --yes @hermespilot/link doctor --install");
       console.log(`你可以直接运行：${commandPath} pair`);
       if (process.platform !== "win32") {
         console.log(`或者先补 PATH：export PATH="${globalBinDir}:$PATH"`);
+      } else {
+        console.log(`或者把这个目录加入当前用户的 Path，然后重新打开终端：${globalBinDir}`);
       }
     }
   } else {
@@ -111,9 +114,12 @@ async function main() {
       console.log(
         `If your shell cannot find \`hermeslink\`, npm's global bin directory is not on PATH: ${globalBinDir}`,
       );
+      console.log("You can run a PATH-independent diagnostic first: npx --yes @hermespilot/link doctor --install");
       console.log(`You can run it directly: ${commandPath} pair`);
       if (process.platform !== "win32") {
         console.log(`Or add it to PATH first: export PATH="${globalBinDir}:$PATH"`);
+      } else {
+        console.log(`Or add this directory to your user Path, then open a new terminal: ${globalBinDir}`);
       }
     }
   }