@actionway/cli 0.18.0 → 0.18.2

package/README.md

@@ -3,15 +3,38 @@
 actionway CLI 的本地端壳（迁移文档 `docs/DL_TO_ACTIONWAY_CLI_MIGRATION.md` §3.2 / §3.4）：
 终端用户在自己机器上的 Coding Agent（Codex / Claude Code）通过它调用 Actionway 能力。
 
+## 安装
+
+要求 Node.js 20 或更新版本；CI 覆盖 Node.js 20 和 22。Windows 使用 npm 生成的 `.cmd` 入口，避免 PowerShell
+执行策略阻止 `.ps1` shim：
+
+```powershell
+npm.cmd install --global @actionway/cli@latest
+actionway.cmd doctor
+actionway.cmd init
+```
+
+macOS / Linux：
+
+```bash
+npm install --global @actionway/cli@latest
+actionway doctor
+actionway init
+```
+
+`doctor` 只输出脱敏后的 Node/npm、registry、global PATH、配置目录、loopback
+和 OAuth discovery 检查；它不会修改 npm、代理、CA、PATH 或 PowerShell policy。
+
 - **auth 唯一途径：Clerk OAuth（PKCE）**。issuer / client_id 运行时从
   `{public origin}/api/auth/cli-config` 发现；浏览器授权走随机 `127.0.0.1` 回调端口；
-  凭据存 `~/.actionway/credentials.json`（0600 owner-only 文件，可用
-  `ACTIONWAY_CONFIG_DIR` 重定向）。CLI 从不打印或存储 OAuth client secret。
+  凭据存 `~/.actionway/credentials.json`（POSIX 上为 0600 owner-only 文件；
+  Windows 上 chmod 无效，保密性依赖 `%USERPROFILE%` 的继承 ACL——不要把
+  `ACTIONWAY_CONFIG_DIR` 指到共享目录）。CLI 从不打印或存储 OAuth client secret。
 - **命令面 = 明码写出的注册表**（无 profile flag、无运行期分叉）：
   - `tools search / inspect / call` 是长尾 capability 的规范发现与执行面；
   - 高频 typed command 继续提供参数与文件 UX，但投影到同一个 Tool Call；
   - `account usage / wallet / transactions` 只读 Actionway Business 数据；
-  - 本壳另有 `init` / `update` / `login` / `logout` / `whoami`，cli-core
+  - 本壳另有 `init` / `doctor` / `update` / `login` / `logout` / `whoami`，cli-core
   继续提供 wait/poll 与已冻结的共享 typed commands。
 
 - **账户响应无本地换算**：`account` 响应同时保留精确整数 micros 与可直接展示的 USD 十进制字符串；钱包包含快照更新时间，交易包含状态、说明、完成时间和 signed balance delta。Usage/Transactions 支持 ISO 时间窗口、领域筛选和 opaque cursor，返回的 summary 覆盖完整筛选集合而非当前页。CLI 不自行换算资金，也不改变服务端返回的字段语义。

package/assets/skill/actionway/SKILL.md

@@ -11,7 +11,7 @@ Use the installed `actionway` CLI and its server-backed Capability Registry as t
 
 ## Prepare
 
-1. Run Actionway commands with network access and permission to read `~/.actionway`. If a sandboxed command reports `E_NOT_AUTHENTICATED` for an already logged-in user, rerun the same command with host permission before starting login again.
+1. Run Actionway commands with network access and permission to read `~/.actionway`. On Windows, use the generated `actionway.cmd` entrypoint when PowerShell policy blocks `actionway.ps1`. If setup or update fails, run `actionway.cmd doctor` on Windows or `actionway doctor` elsewhere from the host terminal and preserve its failed check IDs; do not weaken registry, proxy, CA, PATH, or PowerShell policy without user approval. If a sandboxed command reports `E_NOT_AUTHENTICATED` for an already logged-in user, rerun the same command with host permission before starting login again.
 2. If the user supplied a pending `job_ref`, skip updating and immediately run `actionway wait --job-ref=<uuid>`.
 3. Otherwise, once per Agent session, run `actionway update --check`. Continue with the installed CLI if the check is unavailable. If an update is available, run `actionway update` before starting a new call, then refresh this Skill from the returned `skill_source` for the next Agent session.
 4. Compare this Skill's `metadata.version` with successful command output `cli_version`. If they differ, replace the installed Actionway Skill with the directory at `skill_source`, tell the user once that the refreshed instructions apply from the next session, and continue the current task. Follow any output `notes`, especially minimum-version instructions.

package/dist/index.js

@@ -3040,6 +3040,9 @@ function exitCodeFor(code) {
     case "E_FILE_MISSING":
     case "E_FILE_PARSE":
     case "E_UNKNOWN_OPTION":
+    case "E_NODE_UNSUPPORTED":
+    case "E_NPM_NOT_FOUND":
+    case "E_GLOBAL_PREFIX":
     case "E_DEPRECATED":
       return 2;
     default:
@@ -12145,7 +12148,6 @@ import { createServer } from "node:http";
 import { join as join2 } from "node:path";
 
 // src/lib/update-state.ts
-import { execFileSync, spawnSync } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -12175,6 +12177,103 @@ function readOwnVersion(moduleUrl = import.meta.url) {
   throw new Error(`cannot determine the installed ${PACKAGE_NAME} version`);
 }
 
+// src/lib/npm-runner.ts
+import { spawnSync } from "node:child_process";
+var DEFAULT_MAX_BUFFER = 1024 * 1024;
+function npmInvocation(args, platform = process.platform, env = process.env) {
+  if (platform === "win32") {
+    const commandProcessor = (env.ComSpec ?? env.COMSPEC ?? "cmd.exe").trim().replace(/^"|"$/g, "") || "cmd.exe";
+    return {
+      command: commandProcessor,
+      args: ["/d", "/s", "/c", "npm.cmd", ...args]
+    };
+  }
+  return { command: "npm", args: [...args] };
+}
+function runNpm(args, options = {}) {
+  const env = options.env ?? process.env;
+  const invocation = npmInvocation(args, options.platform ?? process.platform, env);
+  return spawnSync(invocation.command, invocation.args, {
+    encoding: "utf8",
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: options.timeoutMs ?? 15e3,
+    maxBuffer: DEFAULT_MAX_BUFFER,
+    windowsHide: true
+  });
+}
+function sanitizeDetail(value) {
+  return value.replace(/(\/\/[^:\s]+:)(?:_authToken|_password|username)=[^\s]+/gi, "$1[redacted]").replace(/((?:_authToken|_password|username)\s*[=:]\s*)[^\s]+/gi, "$1[redacted]").replace(/(authorization\s*:\s*(?:bearer|basic)\s+)[^\s]+/gi, "$1[redacted]").replace(/(https?:\/\/)[^@/\s]+@/gi, "$1[redacted]@").trim().slice(0, 500);
+}
+function resultDetail(result) {
+  const error = result.error instanceof Error ? result.error.message : "";
+  return sanitizeDetail(error || result.stderr || result.stdout || `exit ${result.status ?? "signal"}`);
+}
+var HINTS = {
+  E_NODE_UNSUPPORTED: "install Node.js 20 or newer, open a new terminal, and retry",
+  E_NPM_NOT_FOUND: "install Node.js with npm and make sure npm/npm.cmd is available in PATH",
+  E_GLOBAL_PREFIX: "use a user-writable npm global prefix; do not elevate without reviewing the target path",
+  E_NPM_REGISTRY: "check the npm registry, @actionway scope mapping, proxy, and corporate CA configuration"
+};
+var NPM_ERROR_CODE_MAP = {
+  EBADENGINE: "E_NODE_UNSUPPORTED",
+  EACCES: "E_GLOBAL_PREFIX",
+  EPERM: "E_GLOBAL_PREFIX",
+  E401: "E_NPM_REGISTRY",
+  E403: "E_NPM_REGISTRY",
+  E404: "E_NPM_REGISTRY",
+  E407: "E_NPM_REGISTRY",
+  E408: "E_NPM_REGISTRY",
+  E429: "E_NPM_REGISTRY",
+  ETIMEDOUT: "E_NPM_REGISTRY",
+  ECONNRESET: "E_NPM_REGISTRY",
+  ECONNREFUSED: "E_NPM_REGISTRY",
+  ENETUNREACH: "E_NPM_REGISTRY",
+  EHOSTUNREACH: "E_NPM_REGISTRY",
+  EAI_AGAIN: "E_NPM_REGISTRY",
+  ENOTFOUND: "E_NPM_REGISTRY",
+  SELF_SIGNED_CERT_IN_CHAIN: "E_NPM_REGISTRY",
+  UNABLE_TO_GET_ISSUER_CERT_LOCALLY: "E_NPM_REGISTRY",
+  UNABLE_TO_VERIFY_LEAF_SIGNATURE: "E_NPM_REGISTRY",
+  CERT_HAS_EXPIRED: "E_NPM_REGISTRY",
+  DEPTH_ZERO_SELF_SIGNED_CERT: "E_NPM_REGISTRY"
+  // npm 自身的 ENOENT（缓存/rename 竞态等本地文件问题）可重试，
+  // 不属于"npm 未安装"——那只由 spawn 层的 error/9009 判定。
+};
+function classifyNpmFailure(result, searchable) {
+  const spawnError = result.error;
+  if (spawnError?.code === "ENOENT") return "E_NPM_NOT_FOUND";
+  if (result.status === 9009) return "E_NPM_NOT_FOUND";
+  const codeToken = /npm (?:ERR!|error) code ([A-Z0-9_]+)/i.exec(searchable)?.[1]?.toUpperCase();
+  if (codeToken) {
+    const mapped = NPM_ERROR_CODE_MAP[codeToken];
+    if (mapped) return mapped;
+    if (/^(?:CERT_|ERR_TLS_|UNABLE_TO_)/.test(codeToken)) return "E_NPM_REGISTRY";
+    return "E_UPDATE_FAILED";
+  }
+  if (/unsupported engine|not compatible with your version of node/i.test(searchable)) return "E_NODE_UNSUPPORTED";
+  if (/not recognized as an internal or external command|npm(?:\.cmd)?: (?:command )?not found/i.test(searchable))
+    return "E_NPM_NOT_FOUND";
+  if (/permission denied|operation not permitted/i.test(searchable)) return "E_GLOBAL_PREFIX";
+  if (/self[- ]signed certificate|unable to (?:get|verify) .*certificate|getaddrinfo|socket hang up|network timeout/i.test(searchable))
+    return "E_NPM_REGISTRY";
+  return "E_UPDATE_FAILED";
+}
+function npmFailure(result, operation) {
+  const detail = resultDetail(result);
+  const searchable = `${detail}
+${result.stderr}
+${result.stdout}`;
+  const code = classifyNpmFailure(result, searchable);
+  const hint = HINTS[code] ?? "retry from a normal host terminal or reinstall @actionway/cli@latest (use npm.cmd on Windows)";
+  return new CliError(code, `${operation} failed: ${detail || "npm exited unsuccessfully"}`, hint);
+}
+function runNpmText(args, operation, options = {}) {
+  const result = runNpm(args, options);
+  if (result.error || result.status !== 0) throw npmFailure(result, operation);
+  return result.stdout.trim();
+}
+
 // src/lib/update-state.ts
 var PACKAGE_NAME2 = "@actionway/cli";
 var UPDATE_STATE_BASENAME = "update.json";
@@ -12275,30 +12374,22 @@ function recordVersionSignal(signal, env = process.env, now = /* @__PURE__ */ ne
     env
   );
 }
-function npmExecutable() {
-  return process.platform === "win32" ? "npm.cmd" : "npm";
-}
 function fetchLatestVersionFromNpm(env) {
-  const output = execFileSync(npmExecutable(), ["view", `${PACKAGE_NAME2}@latest`, "version"], {
-    encoding: "utf8",
-    env,
-    stdio: ["ignore", "pipe", "pipe"],
-    timeout: 15e3
-  }).trim();
+  const output = runNpmText(
+    ["view", `${PACKAGE_NAME2}@latest`, "version"],
+    `npm registry check for ${PACKAGE_NAME2}@latest`,
+    { env, timeoutMs: 15e3 }
+  );
   const version = output.split(/\r?\n/).at(-1)?.trim() ?? "";
   if (!version) throw new Error(`npm returned no version for ${PACKAGE_NAME2}@latest`);
   return version;
 }
 function installFromNpm(env) {
-  const result = spawnSync(
-    npmExecutable(),
+  runNpmText(
     ["install", "--global", "--no-audit", "--no-fund", "--no-update-notifier", `${PACKAGE_NAME2}@latest`],
-    { encoding: "utf8", env, stdio: ["ignore", "pipe", "pipe"], timeout: 12e4 }
+    `npm global update for ${PACKAGE_NAME2}`,
+    { env, timeoutMs: 12e4 }
   );
-  if (result.status !== 0) {
-    const detail = (result.stderr || result.stdout || `exit ${result.status ?? "signal"}`).trim().slice(0, 500);
-    throw new Error(`npm update failed: ${detail}`);
-  }
 }
 function isFresh(state, now) {
   if (!state.checked_at || !state.latest_version) return false;
@@ -12907,12 +12998,232 @@ function registerAccountCommands(program2, getTransport3) {
   account.command("transactions").description("Query wallet top-ups, charges, promotions, refunds, and other fund movements.").option("--limit <count>", "Maximum records in this page (1-50).").option("--cursor <cursor>", "Opaque nextCursor returned by the previous page.").option("--from <date>", "Inclusive ISO date or timestamp (UTC for date-only values).").option("--to <date>", "Exclusive ISO date or timestamp (UTC for date-only values).").option("--status <status>", "pending, succeeded, or failed.").option("--kind <kind>", "top_up, charge, refund, dispute, or promotion kind.").action((options) => read(accountEndpoint("transactions", options), getTransport3));
 }
 
+// src/commands/doctor.ts
+import { spawnSync as spawnSync2 } from "node:child_process";
+import { existsSync as existsSync2, rmSync as rmSync2, statSync, writeFileSync as writeFileSync3 } from "node:fs";
+import { createServer as createServer2 } from "node:http";
+import { randomBytes as randomBytes2 } from "node:crypto";
+import { dirname as dirname3, join as join3, posix, win32 } from "node:path";
+var PACKAGE_NAME3 = "@actionway/cli";
+function pass(id, message) {
+  return { id, status: "pass", message };
+}
+function warn(id, message, hint) {
+  return { id, status: "warn", message, hint };
+}
+function fail2(id, message, hint) {
+  return { id, status: "fail", message, hint };
+}
+function commandOutput(result) {
+  return !result.error && result.status === 0 ? result.stdout.trim() : null;
+}
+function safeRegistry(value) {
+  try {
+    const url = new URL(value);
+    url.username = "";
+    url.password = "";
+    return url.toString();
+  } catch {
+    return value.trim() ? "[invalid registry URL]" : "[empty registry URL]";
+  }
+}
+function pathApi(platform) {
+  return platform === "win32" ? win32 : posix;
+}
+function samePath(left, right, platform) {
+  const api = pathApi(platform);
+  const clean = (value) => api.normalize(value.replace(/^"|"$/g, "").replace(/[\\/]+$/, ""));
+  const a = clean(left);
+  const b = clean(right);
+  return platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+function pathContains(directory, env, platform) {
+  const api = pathApi(platform);
+  return (env.PATH ?? env.Path ?? "").split(api.delimiter).some((entry) => entry && samePath(entry, directory, platform));
+}
+function defaultWritable(path) {
+  let candidate = path;
+  while (!existsSync2(candidate) && dirname3(candidate) !== candidate) candidate = dirname3(candidate);
+  try {
+    if (!statSync(candidate).isDirectory()) return false;
+    const probe = join3(candidate, `.actionway-doctor-${randomBytes2(6).toString("hex")}`);
+    writeFileSync3(probe, "");
+    rmSync2(probe, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function checkLoopback() {
+  return new Promise((resolve3, reject) => {
+    const server = createServer2();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => server.close((error) => error ? reject(error) : resolve3()));
+  });
+}
+function defaultResolveCommand(name) {
+  const result = process.platform === "win32" ? spawnSync2("where.exe", [name], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5e3, windowsHide: true }) : spawnSync2("/bin/sh", ["-c", `command -v -- ${name}`], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5e3 });
+  if (result.error || result.status !== 0) return null;
+  return result.stdout.split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? null;
+}
+function powerShellPolicy() {
+  const result = spawnSync2(
+    "powershell.exe",
+    ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", "Get-ExecutionPolicy"],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5e3, windowsHide: true }
+  );
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+function npmCheck(id, result, operation, success) {
+  const output = commandOutput(result);
+  if (output !== null) return success(output);
+  const error = npmFailure(result, operation);
+  return fail2(id, error.message, error.hint ?? "inspect the npm configuration and retry");
+}
+async function diagnoseActionway(options = {}, dependencies = {}) {
+  const env = dependencies.env ?? process.env;
+  const platform = dependencies.platform ?? process.platform;
+  const architecture = dependencies.architecture ?? process.arch;
+  const nodeVersion = dependencies.nodeVersion ?? process.versions.node;
+  const npm = dependencies.runNpm ?? runNpm;
+  const pathExists = dependencies.pathExists ?? existsSync2;
+  const pathWritable = dependencies.pathWritable ?? defaultWritable;
+  const fetchOAuth = dependencies.fetchOAuth ?? fetchCliOAuthConfig;
+  const loopback = dependencies.checkLoopback ?? checkLoopback;
+  const readPolicy = dependencies.readPowerShellPolicy ?? powerShellPolicy;
+  const resolveCommand = dependencies.resolveCommand ?? defaultResolveCommand;
+  const checks = [];
+  const configDir = actionwayConfigDir(env);
+  const nodeMajor = Number.parseInt(nodeVersion.split(".")[0] ?? "", 10);
+  checks.push(
+    Number.isFinite(nodeMajor) && nodeMajor >= 20 ? pass("node", `Node.js ${nodeVersion} is supported.`) : fail2("node", `Node.js ${nodeVersion || "unknown"} is unsupported.`, "install Node.js 20 or newer and reopen the terminal")
+  );
+  if (platform === "linux" && (env.WSL_DISTRO_NAME || env.WSL_INTEROP)) {
+    checks.push(
+      warn(
+        "execution_environment",
+        "WSL detected; browser loopback may not share the Windows host network namespace.",
+        "run Actionway login from the Windows host if the browser callback cannot return"
+      )
+    );
+  } else {
+    checks.push(pass("execution_environment", `${platform}/${architecture} host environment detected.`));
+  }
+  checks.push(
+    pathWritable(configDir) ? pass("config_dir", `Configuration directory is writable: ${configDir}`) : fail2("config_dir", `Configuration directory is not writable: ${configDir}`, "set ACTIONWAY_CONFIG_DIR to a user-writable directory")
+  );
+  const registryResult = npm(["config", "get", "registry"], { env, platform, timeoutMs: 15e3 });
+  checks.push(
+    npmCheck("npm", registryResult, "npm discovery", (registry) => pass("npm", `npm is available; registry is ${safeRegistry(registry)}.`))
+  );
+  const scopeResult = npm(["config", "get", "@actionway:registry"], { env, platform, timeoutMs: 15e3 });
+  const scopeRegistry = commandOutput(scopeResult);
+  if (scopeRegistry && !["null", "undefined"].includes(scopeRegistry.toLowerCase())) {
+    const safe = safeRegistry(scopeRegistry);
+    checks.push(
+      safe.startsWith("https://registry.npmjs.org/") ? pass("scope_registry", `@actionway packages use ${safe}.`) : warn(
+        "scope_registry",
+        `@actionway packages are mapped to ${safe}.`,
+        "make sure that registry mirrors public @actionway/cli, or install from the public npm registry when policy permits"
+      )
+    );
+  } else if (scopeResult.error || scopeResult.status !== 0) {
+    checks.push(warn("scope_registry", "Could not read the @actionway npm scope mapping.", "inspect npm user configuration"));
+  } else {
+    checks.push(pass("scope_registry", "No custom @actionway npm registry mapping is configured."));
+  }
+  const prefixResult = npm(["prefix", "--global"], { env, platform, timeoutMs: 15e3 });
+  const prefix = commandOutput(prefixResult);
+  if (!prefix) {
+    const error = npmFailure(prefixResult, "npm global prefix lookup");
+    checks.push(fail2("global_prefix", error.message, error.hint ?? "inspect npm global configuration"));
+  } else {
+    const api = pathApi(platform);
+    const binDir = platform === "win32" ? prefix : api.join(prefix, "bin");
+    const binName = platform === "win32" ? "actionway.cmd" : "actionway";
+    let resolvedCache;
+    const resolved = () => resolvedCache !== void 0 ? resolvedCache : resolvedCache = resolveCommand("actionway");
+    checks.push(
+      pathContains(binDir, env, platform) ? pass("global_path", `npm global executable directory is in PATH: ${binDir}`) : resolved() ? pass("global_path", `actionway resolves from PATH at ${resolved()} (outside the npm global prefix ${binDir}).`) : fail2("global_path", `npm global executable directory is not in PATH: ${binDir}`, "add it to the user PATH and open a new terminal")
+    );
+    checks.push(
+      pathExists(api.join(binDir, binName)) ? pass("command", `${binName} is installed in the npm global prefix.`) : resolved() ? pass("command", `actionway command resolves at ${resolved()}.`) : fail2("command", `${binName} was not found in the npm global prefix.`, "reinstall @actionway/cli@latest in the same Node/npm environment")
+    );
+  }
+  if (platform === "win32") {
+    const policy = readPolicy();
+    checks.push(
+      policy && ["Restricted", "AllSigned"].includes(policy) ? warn(
+        "powershell_policy",
+        `PowerShell execution policy is ${policy}; npm's actionway.ps1 shim may be blocked.`,
+        "use actionway.cmd; do not weaken organization policy without approval"
+      ) : pass("powershell_policy", `PowerShell execution policy is ${policy || "not available"}; actionway.cmd remains the stable entrypoint.`)
+    );
+  }
+  try {
+    await loopback();
+    checks.push(pass("loopback", "A random 127.0.0.1 callback port can be opened."));
+  } catch (error) {
+    checks.push(
+      fail2(
+        "loopback",
+        `Cannot open the local OAuth callback: ${error instanceof Error ? error.message : String(error)}`,
+        "run login from a normal host terminal and check firewall or sandbox policy"
+      )
+    );
+  }
+  if (options.network === false) {
+    checks.push({ id: "npm_registry", status: "skip", message: "npm registry check was skipped." });
+    checks.push({ id: "actionway_oauth", status: "skip", message: "Actionway OAuth discovery check was skipped." });
+  } else {
+    const packageResult = npm(["view", `${PACKAGE_NAME3}@latest`, "version"], { env, platform, timeoutMs: 15e3 });
+    checks.push(
+      npmCheck(
+        "npm_registry",
+        packageResult,
+        "Actionway package lookup",
+        (version) => pass("npm_registry", `${PACKAGE_NAME3}@latest is reachable (${version.split(/\r?\n/).at(-1)}).`)
+      )
+    );
+    try {
+      await fetchOAuth(resolveGatewayUrl(void 0, env));
+      checks.push(pass("actionway_oauth", "Actionway OAuth discovery is reachable."));
+    } catch (error) {
+      checks.push(
+        fail2(
+          "actionway_oauth",
+          `Actionway OAuth discovery failed: ${error instanceof Error ? error.message : String(error)}`,
+          "check actionway.ai access, proxy, DNS, and corporate CA configuration"
+        )
+      );
+    }
+  }
+  return {
+    ready: !checks.some((check) => check.status === "fail"),
+    platform,
+    architecture,
+    node_version: nodeVersion,
+    config_dir: configDir,
+    checks
+  };
+}
+function registerDoctorCommand(program2) {
+  program2.command("doctor").description("Diagnose Node, npm, PATH, registry, configuration, and local OAuth callback readiness.").option("--no-network", "skip npm registry and Actionway OAuth discovery checks").action(async (options) => {
+    const report = await diagnoseActionway({ network: options.network !== false });
+    const command = process.platform === "win32" ? "actionway.cmd" : "actionway";
+    ok({
+      ...report,
+      hint: report.ready ? `Actionway CLI prerequisites are ready. Run \`${command} init\`.` : `Resolve the failed checks, then run \`${command} doctor\` again.`
+    });
+  });
+}
+
 // src/lib/install-session.ts
 import { randomUUID as randomUUID5 } from "node:crypto";
 
 // src/lib/skill.ts
-import { cpSync, existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync4, realpathSync as realpathSync2, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname3, join as join3, resolve as resolve2 } from "node:path";
+import { cpSync, existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync4, realpathSync as realpathSync2, rmSync as rmSync3, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname4, join as join4, resolve as resolve2 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 var InitError = class extends Error {
   hint;
@@ -12924,17 +13235,18 @@ var InitError = class extends Error {
 };
 var ACTIONWAY_SKILL_INSTRUCTION = "Install this skill from `source` into your agent's skill directory and make sure it loads in future sessions. If a skill named `actionway` already exists there, replace it only when it is an earlier Actionway skill (check its frontmatter metadata.version); otherwise ask the user first.";
 function resolveBundledSkill(moduleUrl = import.meta.url) {
-  const here = dirname3(fileURLToPath3(moduleUrl));
+  const here = dirname4(fileURLToPath3(moduleUrl));
   for (const candidate of [resolve2(here, "../assets/skill/actionway"), resolve2(here, "../../assets/skill/actionway")]) {
-    if (existsSync2(join3(candidate, "SKILL.md"))) return realpathSync2(candidate);
+    if (existsSync3(join4(candidate, "SKILL.md"))) return realpathSync2(candidate);
   }
   throw new InitError("the bundled Actionway Skill is missing", "reinstall @actionway/cli, then run `actionway init` again");
 }
 function skillSourcePath(env = process.env) {
-  return join3(actionwayConfigDir(env), "skill", "actionway");
+  return join4(actionwayConfigDir(env), "skill", "actionway");
 }
 function stampSkillVersion(skillMarkdown, version) {
-  const lines = skillMarkdown.split("\n");
+  const newline = skillMarkdown.includes("\r\n") ? "\r\n" : "\n";
+  const lines = skillMarkdown.split(/\r?\n/);
   if (lines[0]?.trim() !== "---") return skillMarkdown;
   let closing = lines.indexOf("---", 1);
   if (closing < 0) return skillMarkdown;
@@ -12958,28 +13270,28 @@ function stampSkillVersion(skillMarkdown, version) {
     for (let index = metadataIndex + 1; index < metadataEnd; index += 1) {
       if (/^\s{2}version\s*:/.test(lines[index] ?? "")) {
         lines[index] = versionLine;
-        return lines.join("\n");
+        return lines.join(newline);
       }
     }
     lines.splice(metadataIndex + 1, 0, versionLine);
-    return lines.join("\n");
+    return lines.join(newline);
   }
   lines.splice(closing, 0, "metadata:", versionLine);
-  return lines.join("\n");
+  return lines.join(newline);
 }
 function materializeSkill(options = {}) {
   const env = options.env ?? process.env;
   const source = options.source ? realpathSync2(options.source) : resolveBundledSkill();
-  if (!existsSync2(join3(source, "SKILL.md"))) {
+  if (!existsSync3(join4(source, "SKILL.md"))) {
     throw new InitError("the Actionway Skill source is invalid", "reinstall @actionway/cli and retry init");
   }
   const version = options.version ?? readOwnVersion();
   const target = skillSourcePath(env);
-  mkdirSync3(dirname3(target), { recursive: true, mode: 448 });
-  rmSync2(target, { recursive: true, force: true });
+  mkdirSync3(dirname4(target), { recursive: true, mode: 448 });
+  rmSync3(target, { recursive: true, force: true });
   cpSync(source, target, { recursive: true });
-  const skillPath = join3(target, "SKILL.md");
-  writeFileSync3(skillPath, stampSkillVersion(readFileSync4(skillPath, "utf8"), version));
+  const skillPath = join4(target, "SKILL.md");
+  writeFileSync4(skillPath, stampSkillVersion(readFileSync4(skillPath, "utf8"), version));
   return { source: target, version, instruction: ACTIONWAY_SKILL_INSTRUCTION };
 }
 
@@ -13140,12 +13452,12 @@ function registerInitCommand(program2) {
 }
 
 // src/commands/update.ts
-import { spawnSync as spawnSync2 } from "node:child_process";
+import { spawnSync as spawnSync3 } from "node:child_process";
 function refreshSkillWithNewBinary() {
   try {
     const binPath = process.argv[1];
     if (!binPath) return { refreshed: false };
-    const result = spawnSync2(process.execPath, [binPath, "init", "--skill-only"], {
+    const result = spawnSync3(process.execPath, [binPath, "init", "--skill-only"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
       timeout: 3e4
@@ -13176,8 +13488,11 @@ function registerUpdateCommand(program2) {
         hint: skillRefresh.refreshed ? "The new CLI will be used by the next actionway command. Refresh the skill installed in your agent's skill directory from `skill.source`; the updated instructions apply from the next session." : "The new CLI will be used by the next actionway command. Run `actionway init` to refresh the staged skill, then reinstall it into your agent's skill directory."
       });
     } catch (error) {
+      if (error instanceof CliError) {
+        fail({ code: error.code, message: error.message, hint: error.hint, extra: error.extra });
+      }
       fail({
-        code: "E_BACKEND",
+        code: "E_UPDATE_FAILED",
         message: error instanceof Error ? error.message : String(error),
         hint: "retry later or reinstall @actionway/cli@latest"
       });
@@ -13426,6 +13741,7 @@ function buildProgram() {
   program2.version(version);
   program2.description("Actionway CLI: run Actionway media and research capabilities from your local agent.");
   registerInitCommand(program2);
+  registerDoctorCommand(program2);
   registerUpdateCommand(program2);
   registerAuthCommands(program2);
   registerAccountCommands(program2, getTransport2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actionway/cli",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "actionway CLI 的本地端壳：Clerk OAuth 鉴权 + cli-core 共享命令面 + init / update / skill 物化 / 版本三链路（终端用户本地 Codex / Claude Code 使用）",
   "type": "module",
   "bin": {
@@ -26,7 +26,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/index.js --banner:js='import { createRequire } from \"node:module\"; const require = createRequire(import.meta.url);'",
+    "build": "node scripts/build.mjs",
     "dev": "tsx src/index.ts",
     "test": "vitest --run",
     "typecheck": "tsc -p tsconfig.json --noEmit"