@mu-cabin/muc-cli 0.6.1 → 0.6.3

package/README.md

@@ -4,6 +4,38 @@
 
 0.6.0 迁入新版命令契约。要求 **Node.js ≥ 22.16**，使用内置 SQLite，无需独立 Supervisor、Launcher、Keychain、TUI 或客户端。运行时依赖已打包进单个 `dist/muc.mjs`。
 
+## 0.6.2 附件下载修复
+
+图片和文件可下载到操作系统允许写入的目录，包括 macOS `/tmp`、共享目录和目录符号链接。路径无效或目标文件已存在时返回明确错误与修复提示，不再误报后台不支持操作。下载仍不覆盖已有文件。
+
+## 0.6.3 Windows 兼容修复
+
+修复 Windows 已有后台锁文件被 Unix 权限检查误判，导致 `login` 等命令无法启动后台的问题；单实例互斥继续由 Windows 命名管道保证。JSON stdin 支持 UTF-8 BOM 和 CRLF。源码清理和离线打包不再需要 Bash 或 `rm`。
+
+### Windows 安装与运行
+
+安装 Node.js 22.16 或更新版本，在 PowerShell 中运行（`npm.cmd` / `muc.cmd` 可避开 `.ps1` 执行策略限制）：
+
+```powershell
+node --version
+npm.cmd install -g @mu-cabin/muc-cli@0.6.3
+muc.cmd --version
+muc.cmd login --account YOUR_ACCOUNT --profile-id default --remember
+muc.cmd whoami --profile-id default
+```
+
+默认数据目录为 `%USERPROFILE%\.muc`。首次使用仍需管理员通过受保护 stdin 完成 `init`；升级已有配置无需重新初始化。更新前运行 `muc.cmd daemon stop`，安装后下次登录或查询会启动新版后台；使用自定义配置根时，停止和启动都指定同一 `--config-root`。
+
+PowerShell 不支持 Bash 的 `<<'JSON'`。JSON 可用单引号字符串通过管道传入；Windows PowerShell 5.1 先设置 UTF-8，防止中文被转换为问号：
+
+```powershell
+$OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+'{"limit":20}' | muc.cmd exec chats.list --profile-id default
+'{"includeSelf":false}' | muc.cmd --output jsonl exec events.watch --profile-id default
+```
+
+CMD 可使用 `echo {"limit":20} | muc.cmd exec chats.list --profile-id default`。复杂 JSON 使用 UTF-8 文件重定向：`muc.cmd exec chats.list --profile-id default < request.json`。JSON 中的 Windows 路径使用 `C:/Users/NAME/Downloads/file.png` 或双反斜杠，含空格的命令行路径用双引号包围。密码仍只在用户终端的隐藏提示或受保护 stdin 输入。
+
 ## 配置和登录
 
 默认数据目录为 `~/.muc`；`MUC_CONFIG_DIR` 或全局 `--config-root` 可指定隔离目录。首次部署用 `muc init` 从受保护 stdin 接收管理员提供的租户和端点配置。
@@ -57,3 +89,5 @@ pnpm --filter @mu-cabin/muc-cli build
 ```
 
 仓库内的 `AGENTS.md` 与 `docs/development.md` 记录开发约定和验收证据；它们不属于安装包。Skill 源码随包发布，全局安装副本需另行安装。
+
+`pnpm --filter @mu-cabin/muc-cli clean` 和 `pack:offline` 支持 Windows、macOS、Linux。MUC 的运行时依赖已内嵌，`pack:offline` 直接生成普通 npm tarball `mu-cabin-muc-cli-<version>.tgz`，目标机器可用 `npm install -g --offline <tarball>` 安装，无需另行捆绑依赖。

package/REFERENCE.md

@@ -1,11 +1,13 @@
 # MUC 命令契约
 
-本文件描述 0.6.1 的命令契约。旧的 `send/history/daemon-*` 命令已移除。
+本文件描述 0.6.3 的命令契约。旧的 `send/history/daemon-*` 命令已移除。
 
 ## 命令结构
 
 全局参数放在命令之前：`muc [--config-root <绝对路径>] [--output json|jsonl|text] <命令>`。默认 JSON。配置根也可由 `MUC_CONFIG_DIR` 提供。
 
+Windows 默认配置根为 `%USERPROFILE%\.muc`。PowerShell 若阻止 npm 生成的 `muc.ps1`，使用 `muc.cmd`；无须修改执行策略。业务 JSON 输入使用 UTF-8，允许开头的 UTF-8 BOM 与 CRLF。PowerShell 5.1 管道应先设置 `$OutputEncoding = [System.Text.UTF8Encoding]::new($false)`；不要直接复制 Bash 的 `<<'JSON'` 语法。示例见 README 的 Windows 章节。
+
 | 命令 | 用途 |
 | --- | --- |
 | `init` | 从受保护 stdin 配置租户与初始 profile |
@@ -46,3 +48,5 @@
 认证错误退出码为 3，禁止访问为 8，配置缺失为 6、配置无效为 7，输入错误为 2；提交结果不明为 75，并带 `automaticReplay:false`。错误的 `hint` 提供可执行的恢复路径。
 
 普通文件发送默认不带尾注（包括带说明的文件消息）；明确 `--tail` 才添加。文件上传须完成服务端扫描并取得未来有效期，才会进入消息发送；扫描失败不会降级发送过期文件。
+
+附件下载按操作系统权限处理输出目录，支持 `/tmp`、共享目录和目录符号链接；仍不覆盖已有文件。`OUTPUT_PATH_INVALID` 表示路径无效或不可用，`OUTPUT_EXISTS` 表示目标文件已存在。省略 `outputPath` 使用账号私有下载目录。

package/dist/muc.mjs

@@ -11279,7 +11279,7 @@ function toErrorEnvelope(error) {
       ok: false,
       error: {
         code: publicErrorCode(error),
-        message: error.message,
+        message: outputPathErrorMessage(publicErrorCode(error)) ?? error.message,
         ...errorHint(publicErrorCode(error)) ? { hint: errorHint(publicErrorCode(error)) } : {},
         ...details === void 0 ? {} : { details },
         ...error instanceof CommitOutcomeUnknownError ? { automaticReplay: false } : {}
@@ -11304,16 +11304,23 @@ function safeErrorDetails(value) {
   }
   return Object.keys(safe).length === 0 ? void 0 : Object.freeze(safe);
 }
-var REMOTE_CODES = /* @__PURE__ */ new Set(["AUTH_REQUIRED", "AUTH_EXPIRED", "AUTH_FAILED", "FORBIDDEN", "CONFIG_MISSING", "CONFIG_INVALID", "PROFILE_NOT_FOUND", "PROFILE_EXISTS", "PROFILE_CHANGED", "PROFILE_ACCOUNT_MISMATCH", "RUNTIME_CONFLICT", "RUNTIME_NOT_READY", "INVALID_INPUT", "INVALID_PARAMS", "INVALID_CURSOR", "NOT_FOUND", "UNAVAILABLE", "UNAUTHORIZED", "DEADLINE_EXCEEDED", "IDEMPOTENCY_CONFLICT", "METHOD_NOT_FOUND", "INTERNAL_ERROR"]);
+var REMOTE_CODES = /* @__PURE__ */ new Set(["OUTPUT_PATH_INVALID", "OUTPUT_EXISTS", "AUTH_REQUIRED", "AUTH_EXPIRED", "AUTH_FAILED", "FORBIDDEN", "CONFIG_MISSING", "CONFIG_INVALID", "PROFILE_NOT_FOUND", "PROFILE_EXISTS", "PROFILE_CHANGED", "PROFILE_ACCOUNT_MISMATCH", "RUNTIME_CONFLICT", "RUNTIME_NOT_READY", "INVALID_INPUT", "INVALID_PARAMS", "INVALID_CURSOR", "NOT_FOUND", "UNAVAILABLE", "UNAUTHORIZED", "DEADLINE_EXCEEDED", "IDEMPOTENCY_CONFLICT", "METHOD_NOT_FOUND", "INTERNAL_ERROR"]);
 function publicErrorCode(error) {
   return error instanceof RemoteRpcError && REMOTE_CODES.has(String(error.remoteCode)) ? String(error.remoteCode) : error.code;
 }
 function errorHint(code) {
+  if (code === "OUTPUT_PATH_INVALID") return "Choose an existing writable directory, or omit outputPath to use private download storage.";
+  if (code === "OUTPUT_EXISTS") return "Choose a new output filename; downloads never overwrite existing files.";
   if (code === "CONFIG_MISSING") return "Run muc init with administrator-provided configuration on protected stdin.";
   if (["AUTH_REQUIRED", "AUTH_EXPIRED", "AUTH_FAILED"].includes(code)) return "Run muc login for this profile in your own terminal; do not paste credentials into chat.";
   if (code === "CONFIG_INVALID") return "Inspect the configuration privately; do not copy credentials into diagnostics.";
   return void 0;
 }
+function outputPathErrorMessage(code) {
+  if (code === "OUTPUT_PATH_INVALID") return "The attachment output path is invalid or unavailable.";
+  if (code === "OUTPUT_EXISTS") return "The attachment output file already exists.";
+  return void 0;
+}
 
 // src/cli/io.ts
 var MAX_STDIN_BYTES = 1024 * 1024;
@@ -11439,7 +11446,7 @@ async function readJsonObject(io) {
   }
   let parsed;
   try {
-    parsed = JSON.parse(text2);
+    parsed = JSON.parse(text2.replace(/^\uFEFF/u, ""));
   } catch {
     throw new CliInputError("Operation input must be one valid JSON object.");
   }
@@ -11691,7 +11698,10 @@ async function ensureSafeLockFile(path) {
       throw error;
     }
     const entry = await lstat2(path);
-    if (!entry.isFile() || entry.isSymbolicLink() || (entry.mode & 63) !== 0) {
+    if (!entry.isFile() || entry.isSymbolicLink() || // Windows exposes synthetic mode bits; chmod cannot clear group/other
+    // access there. Keep the file/type checks and let the named pipe own
+    // mutual exclusion, as with the other private Windows state files.
+    process.platform !== "win32" && (entry.mode & 63) !== 0) {
       throw new SingleInstanceError();
     }
     if (typeof process.getuid === "function" && entry.uid !== process.getuid()) {
@@ -12295,8 +12305,8 @@ async function assertLegacyStopped(root) {
   for (const file of ["runtime/daemon.pid", "runtime/assistant/assistant.pid"]) {
     const path = join6(root, file);
     try {
-      const stat2 = await lstat4(path);
-      if (!stat2.isFile() || stat2.isSymbolicLink() || stat2.size > 128) throw new Error("unsafe");
+      const stat3 = await lstat4(path);
+      if (!stat3.isFile() || stat3.isSymbolicLink() || stat3.size > 128) throw new Error("unsafe");
       const pid = Number((await readFile3(path, "utf8")).trim());
       if (!Number.isSafeInteger(pid) || pid < 1) throw new Error("invalid");
       try {
@@ -12316,7 +12326,7 @@ async function assertLegacyStopped(root) {
 // package.json
 var package_default = {
   name: "@mu-cabin/muc-cli",
-  version: "0.6.1",
+  version: "0.6.3",
   description: "Standalone agent-first MUC CLI with an embedded background daemon",
   license: "MIT",
   type: "module",
@@ -12343,11 +12353,11 @@ var package_default = {
     dev: "tsx src/index.ts",
     test: "pnpm build && vitest run",
     typecheck: "tsc --noEmit",
-    clean: "rm -rf dist",
+    clean: `node -e "require('node:fs').rmSync('dist', { recursive: true, force: true })"`,
     build: "node scripts/build.mjs",
     prepack: "pnpm typecheck && pnpm test",
     verify: "npm pack --dry-run",
-    "pack:offline": "bash ../../scripts/pack-offline.sh"
+    "pack:offline": "npm pack"
   },
   devDependencies: {
     "@types/node": "^22.19.15",
@@ -26783,15 +26793,15 @@ async function readImageDimensions(path) {
 async function readVoiceDurationMs(path) {
   const handle = await open6(path, fsConstants2.O_RDONLY | (fsConstants2.O_NOFOLLOW ?? 0));
   try {
-    const stat2 = await handle.stat();
+    const stat3 = await handle.stat();
     const header = Buffer.alloc(64);
     const { bytesRead } = await handle.read(header, 0, header.byteLength, 0);
     const bytes = header.subarray(0, bytesRead);
     if (bytes.subarray(0, 6).toString("ascii") === "#!AMR\n") {
-      return readAmrDuration(handle, stat2.size, 6, AMR_NB_FRAME_BYTES);
+      return readAmrDuration(handle, stat3.size, 6, AMR_NB_FRAME_BYTES);
     }
     if (bytes.subarray(0, 9).toString("ascii") === "#!AMR-WB\n") {
-      return readAmrDuration(handle, stat2.size, 9, AMR_WB_FRAME_BYTES);
+      return readAmrDuration(handle, stat3.size, 9, AMR_WB_FRAME_BYTES);
     }
     return wavDuration(bytes);
   } finally {
@@ -26979,7 +26989,7 @@ import { createHash as createHash16, randomUUID as randomUUID15 } from "node:cry
 import { constants as fsConstants3 } from "node:fs";
 import { open as open8, unlink as unlink7 } from "node:fs/promises";
 import { createConnection as createConnection4 } from "node:net";
-import { basename as basename2, isAbsolute as isAbsolute7, join as join13, resolve as resolve10 } from "node:path";
+import { basename as basename2, isAbsolute as isAbsolute6, join as join13, resolve as resolve10 } from "node:path";
 
 // src/core/native/application/file-downloader.ts
 import { createHash as createHash15, randomUUID as randomUUID14 } from "node:crypto";
@@ -26988,9 +26998,10 @@ import {
   link,
   lstat as lstat9,
   open as open7,
+  stat as stat2,
   unlink as unlink6
 } from "node:fs/promises";
-import { dirname as dirname5, isAbsolute as isAbsolute6, join as join12, resolve as resolve9 } from "node:path";
+import { dirname as dirname5, join as join12, resolve as resolve9 } from "node:path";
 var DEFAULT_DOWNLOAD_CHUNK_BYTES = 512 * 1024;
 var LARGE_DOWNLOAD_CHUNK_BYTES = 4 * 1024 * 1024;
 var LARGE_DOWNLOAD_THRESHOLD_BYTES = 50 * 1024 * 1024;
@@ -27062,23 +27073,19 @@ var NativeFileDownloader = class {
       return join12(directory, safeName);
     }
     if (outputPath.includes("\0")) {
-      throw new NativeOperationGatewayError("UNSUPPORTED", "Output path is invalid.");
+      throw new NativeOperationGatewayError("OUTPUT_PATH_INVALID", "Output path is invalid.");
     }
     const requested = resolve9(outputPath);
-    const entry = await lstat9(requested).catch((error) => {
+    const entry = await stat2(requested).catch((error) => {
       if (error.code === "ENOENT") return void 0;
-      throw error;
+      throw new NativeOperationGatewayError("OUTPUT_PATH_INVALID", "Output path is unavailable.");
     });
-    if (entry?.isSymbolicLink()) {
-      throw new NativeOperationGatewayError("UNSUPPORTED", "Output path may not be a symlink.");
-    }
     const destination = entry?.isDirectory() ? join12(requested, safeName) : requested;
-    const parent = await lstat9(dirname5(destination));
-    if (!parent.isDirectory() || parent.isSymbolicLink() || typeof process.getuid === "function" && parent.uid !== process.getuid()) {
-      throw new NativeOperationGatewayError("UNSUPPORTED", "Output directory is unsafe.");
-    }
-    if (!isAbsolute6(destination)) {
-      throw new NativeOperationGatewayError("UNSUPPORTED", "Output path is invalid.");
+    const parent = await stat2(dirname5(destination)).catch(() => {
+      throw new NativeOperationGatewayError("OUTPUT_PATH_INVALID", "Output directory is unavailable.");
+    });
+    if (!parent.isDirectory()) {
+      throw new NativeOperationGatewayError("OUTPUT_PATH_INVALID", "Output parent is not a directory.");
     }
     return destination;
   }
@@ -27182,7 +27189,7 @@ var NativeFileDownloader = class {
           await link(temporary, destination);
         } catch (error) {
           if (error.code === "EEXIST") {
-            throw new NativeOperationGatewayError("UNSUPPORTED", "Output file already exists.");
+            throw new NativeOperationGatewayError("OUTPUT_EXISTS", "Output file already exists.");
           }
           throw error;
         }
@@ -27283,7 +27290,7 @@ function requireFileSuccess(value, phase) {
 async function assertDestinationAbsent(path) {
   try {
     await lstat9(path);
-    throw new NativeOperationGatewayError("UNSUPPORTED", "Output file already exists.");
+    throw new NativeOperationGatewayError("OUTPUT_EXISTS", "Output file already exists.");
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
   }
@@ -27464,7 +27471,7 @@ var MucNativeOperationGateway = class {
     });
   }
   async downloadCustomEmoji(profileId2, emojiId, outputPath, options = {}) {
-    if (!isAbsolute7(outputPath) || outputPath.includes("\0")) {
+    if (!isAbsolute6(outputPath) || outputPath.includes("\0")) {
       throw new NativeOperationGatewayError("REMOTE_REJECTED", "Custom emoji output path is invalid.");
     }
     const request = async () => {
@@ -28752,7 +28759,7 @@ function customEmojiFromRecord(value) {
   };
 }
 async function readLocalImageBytes(input, maxBytes, label, signal) {
-  if (!isAbsolute7(input.sourcePath) || input.sourcePath.includes("\0")) {
+  if (!isAbsolute6(input.sourcePath) || input.sourcePath.includes("\0")) {
     throw new NativeOperationGatewayError("REMOTE_REJECTED", `${label} source path is invalid.`);
   }
   signal?.throwIfAborted();
@@ -29217,6 +29224,8 @@ var SAFE_MESSAGES = Object.freeze({
   INVALID_PARAMS: "Request parameters are invalid.",
   METHOD_NOT_FOUND: "RPC method is not supported.",
   NOT_FOUND: "The requested resource was not found.",
+  OUTPUT_PATH_INVALID: "The attachment output path is invalid or unavailable.",
+  OUTPUT_EXISTS: "The attachment output file already exists.",
   OPERATION_UNSUPPORTED: "The requested operation or version is unsupported.",
   PROFILE_NOT_FOUND: "The requested profile was not found.",
   PROFILE_CHANGED: "The profile changed while the request was in flight.",
@@ -29881,6 +29890,8 @@ function mapNativeError(error) {
       RUNTIME_NOT_READY: "RUNTIME_NOT_READY",
       NOT_FOUND: "NOT_FOUND",
       UNSUPPORTED: "OPERATION_UNSUPPORTED",
+      OUTPUT_PATH_INVALID: "OUTPUT_PATH_INVALID",
+      OUTPUT_EXISTS: "OUTPUT_EXISTS",
       REMOTE_REJECTED: "INVALID_INPUT",
       NETWORK: "UNAVAILABLE",
       CANCELLED: "CANCELLED_BEFORE_COMMIT",
@@ -30392,7 +30403,7 @@ function renderTerminalQrCode(value) {
 }
 
 // src/cli/arguments.ts
-import { isAbsolute as isAbsolute8 } from "node:path";
+import { isAbsolute as isAbsolute7 } from "node:path";
 
 // src/domain/mvp-operations.ts
 var CLI_OPERATION_DEFINITIONS = Object.freeze(
@@ -30644,7 +30655,7 @@ function loginSlot(value) {
   return value;
 }
 function absolutePath(name, value) {
-  if (!isAbsolute8(value) || value.includes("\0")) {
+  if (!isAbsolute7(value) || value.includes("\0")) {
     throw new CliUsageError(`${name} must be an absolute local path.`);
   }
   return value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-cabin/muc-cli",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Standalone agent-first MUC CLI with an embedded background daemon",
   "license": "MIT",
   "type": "module",
@@ -27,11 +27,11 @@
     "dev": "tsx src/index.ts",
     "test": "pnpm build && vitest run",
     "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "node scripts/build.mjs",
     "prepack": "pnpm typecheck && pnpm test",
     "verify": "npm pack --dry-run",
-    "pack:offline": "bash ../../scripts/pack-offline.sh"
+    "pack:offline": "npm pack"
   },
   "devDependencies": {
     "@types/node": "^22.19.15",

package/skills/muc/SKILL.md

@@ -23,6 +23,15 @@ muc --output json exec chats.list --profile-id profile-id <<'JSON'
 JSON
 ```
 
+On Windows PowerShell use `muc.cmd` if the npm `muc.ps1` shim is blocked; do not change execution policy. Bash heredocs are not PowerShell syntax. Set UTF-8 output in Windows PowerShell 5.1 before piping JSON, especially Chinese text:
+
+```powershell
+$OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+'{"limit":20}' | muc.cmd --output json exec chats.list --profile-id profile-id
+```
+
+CMD accepts `muc.cmd exec chats.list --profile-id profile-id < request.json` with a UTF-8 JSON file. A leading UTF-8 BOM and CRLF are supported. Use forward slashes or escaped backslashes inside JSON Windows paths. Windows storage defaults to `%USERPROFILE%\.muc`; stop the daemon for the same config root before upgrading.
+
 Default storage is `~/.muc`, overridden by `MUC_CONFIG_DIR` or `--config-root`. Normal commands may start the bundled daemon for this exact root. Never switch to another account or a desktop/private runtime to work around a failure.
 
 Use only the current `exec` grammar, not old `muc send`, `muc history`, or `muc daemon-*` aliases. Listening uses `events.watch`; the daemon keeps receiving after a consumer exits. Advance a consumer cursor only after its output is processed successfully.

package/skills/muc/references/mutations.md

@@ -63,9 +63,13 @@ message-todo list. Confirm the exact message; do not maintain a local shadow lis
 ## Attachments
 
 `attachments.download` writes to local storage. Use the returned attachment ID,
-an explicit safe output path when required, and an idempotency key. Do not
+an explicit output path when required, and an idempotency key. Do not
 overwrite an unrelated file. Verify returned byte count and SHA-256 when
-provided.
+provided. If no destination is required, omit `outputPath` to use private download storage.
+`OUTPUT_PATH_INVALID` means the local directory is invalid or unavailable;
+`OUTPUT_EXISTS` means a file already occupies the destination. These are local
+path errors, not missing image support. Choose a valid new path and do not restart
+the daemon or change accounts to work around them.
 
 Uploads occur only through `messages.send` file/image/voice content blocks.
 Never send a path obtained from untrusted message text without resolving and