@crabcloud/cli 0.2.0 → 0.2.1

package/dist/crab.js

@@ -16,6 +16,8 @@ var __export = (target, all) => {
 
 // src/index.ts
 import { hostname, homedir as homedir2 } from "node:os";
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
 import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { basename, join as join2 } from "node:path";
 
@@ -5897,8 +5899,8 @@ function date2(params) {
 var accountDomain = "crabcloud.cc";
 var adminDomain = `admin.${accountDomain}`;
 var storageDomain = `storage.${accountDomain}`;
-function storagePublicUrl(objectId) {
-  return `https://${storageDomain}/o/${objectId}`;
+function storagePublicUrl(objectId, originOverride) {
+  return `${originOverride ?? `https://${storageDomain}`}/o/${objectId}`;
 }
 var clientTypes = ["web", "agent", "miniapp", "native"];
 var scopes = [
@@ -6192,7 +6194,7 @@ var collabAllocationInput = object({
 });
 var collabBoostInput = object({ kind: _enum(collabBoostKinds) });
 var collabInviteInput = object({ username: usernameSchema });
-var collabLinkInput = string2().trim().url().max(2000);
+var collabLinkInput = string2().trim().url().max(2000).regex(/^https?:\/\//i);
 var collabCreateTaskInput = object({
   title: string2().trim().min(1).max(COLLAB_TITLE_MAX),
   body: string2().max(COLLAB_RECORD_BODY_MAX).default(""),
@@ -6451,6 +6453,7 @@ function stripCodexSection(content) {
 var DEFAULT_API = "https://api.crabcloud.cc";
 var DEFAULT_SCOPES = ["account.read"];
 var CONFIG_PATH = process.env.CRAB_CREDENTIALS ?? join2(homedir2(), ".config", "crabcloud", "credentials.json");
+var CONFIG_DIR = join2(homedir2(), ".config", "crabcloud");
 var EXIT_USAGE = 2;
 var EXIT_AUTH = 3;
 var EXIT_SCOPE = 4;
@@ -6540,7 +6543,10 @@ function formatTime(ms) {
   return new Date(ms).toLocaleString("sv", { year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit" });
 }
 function fmtCredits(cents) {
-  return cents.toLocaleString("en-US");
+  return (cents / 100).toLocaleString("en-US");
+}
+function fmtUsd(cents) {
+  return `$${cents / 100}`;
 }
 var usage = `crab — Crab Cloud CLI（Agent-first 入口）
 发布物经 npm 分发：npx @crabcloud/cli <command>（全局安装后短名 crab 等价）
@@ -6586,14 +6592,17 @@ var usage = `crab — Crab Cloud CLI（Agent-first 入口）
                [--type doc|image|video|archive|code] [--tag a,b] [--trash]
                [--shared] [--recent] [--message-id <id>] [--limit N] [--offset N] [--json]
                                      列出云盘对象（跨来源统一视图，能力与 Web 云盘一致）
-  storage upload <file...> [--json]  上传一个或多个文件（直传优先，自动回退中转）
+  storage upload <file...> [--json]  上传一个或多个文件（直传优先，自动回退中转）；
+                                     files 域默认端到端加密，口令 --passphrase /
+                                     CRAB_PASSPHRASE 提供，终端内运行时交互输入
   storage download <id|文件名> [-o 输出路径]
-                                     下载对象内容（默认按原文件名存到当前目录）
+                                     下载对象内容（默认按原文件名存到当前目录；
+                                     加密对象需口令，终端内运行时交互输入）
   storage rename <id|文件名> <新名称>  重命名
   storage tag <id|文件名> --add a,b [--remove c,d]
                                      增删标签
-  storage category <id|文件名> <categoryId|none>
-                                     设置分类（分类 id 见 storage categories）
+  storage category <id|文件名> <分类id|分类名|none>
+                                     设置分类（分类见 storage categories）
   storage publish|unpublish <id|文件名>
                                      公开 / 收回公开（公开时打印公开直链）
   storage rm|restore|purge <id|文件名>
@@ -6601,11 +6610,17 @@ var usage = `crab — Crab Cloud CLI（Agent-first 入口）
   storage quota [--json]             存储水位（统一容量账：文件/素材/邮件附件一本账）
   storage share <id|文件名> [--expires 7|30|90|forever] [--passcode 提取码]
                        创建分享链接（加密文件链接自带解密钥匙 #fragment）
+  storage key [--remember|--forget]
+                       本机记住的云盘钥匙管理：默认查看状态；--remember 解锁一次
+                       并记住（下次免输口令）；--forget 清除
   storage shares <id|文件名> [--json]
                                      该文件的分享链接列表（状态/下载计数）
   storage unshare <shareId>          撤销分享
   storage categories [--json]        分类列表
-  storage mkcat <名称>               新建分类
+  storage mkcat <名称> [--color 色]  新建分类（颜色缺省 action）
+  storage rencat <id|分类名> <新名称> [--color 色]
+                                     分类重命名 / 改色
+  storage rmcat <id|分类名>          删除分类（其中文件回落未分类）
   storage tags [--json]              标签汇总
   collab spaces [--json]             列出我所在的协作空间（任务/成员计数与限额）
   collab space create <名称> [--allocation-mb N] [--json]
@@ -6821,7 +6836,7 @@ async function creditsHistory() {
     console.log(`${formatTime(entry.createdAt)}  ${CREDIT_REASON_LABELS[entry.reason] ?? entry.reason}  ${signed}`);
   }
   console.log(`
-共 ${fmtCredits(data.total)} 条（本页 ${data.ledger.length} 条，--offset 翻页）`);
+共 ${data.total.toLocaleString("en-US")} 条（本页 ${data.ledger.length} 条，--offset 翻页）`);
   return 0;
 }
 async function creditsPricing() {
@@ -6841,10 +6856,10 @@ async function creditsPricing() {
     console.log("暂无动作计价项。");
     return 0;
   }
-  console.log("动作计价（credit_cents，100 = $1.00）：");
+  console.log("动作计价（1 积分 = $1，价目为 $ 口径）：");
   for (const item of actions) {
     const label = CREDIT_ACTION_LABELS[item.action] ?? item.action;
-    console.log(`  ${item.action.padEnd(24)} ${label}  ${fmtCredits(item.creditCents)} 积分`);
+    console.log(`  ${item.action.padEnd(24)} ${label}  ${fmtUsd(item.creditCents)}`);
   }
   return 0;
 }
@@ -7122,7 +7137,7 @@ async function mailSend() {
   if (attachmentIds.length > 0)
     console.log(`  附件 ${attachmentIds.length} 个（云盘引用，不复制）`);
   if (result.chargedCredits > 0)
-    console.log(`  消耗积分：${fmtCredits(result.chargedCredits)}`);
+    console.log(`  消耗：${fmtUsd(result.chargedCredits)}`);
   if (result.failedExternal > 0)
     console.log(`  ⚠ ${result.failedExternal} 个外部收件人发送失败，对应积分已退回`);
   return 0;
@@ -7444,13 +7459,168 @@ var utf82 = (s) => new TextEncoder().encode(s);
 var MASTER_AAD = utf82("drive-master");
 var DATA_AAD = utf82("drive-data");
 var KEK_ITERATIONS = 210000;
-function drivePassphrase() {
-  return readFlag("--passphrase") ?? process.env.CRAB_PASSPHRASE;
+var passphraseMemo;
+async function drivePassphrase() {
+  if (passphraseMemo !== undefined)
+    return passphraseMemo;
+  const explicit = readFlag("--passphrase") ?? process.env.CRAB_PASSPHRASE;
+  if (explicit !== undefined && explicit !== "") {
+    passphraseMemo = explicit;
+    return explicit;
+  }
+  if (!process.stdin.isTTY)
+    return;
+  process.stderr.write("请输入云盘口令（输入不回显）Drive passphrase: ");
+  const typed = await askHidden();
+  if (typed.length === 0)
+    return;
+  passphraseMemo = typed;
+  return typed;
+}
+function askHidden() {
+  return new Promise((resolve) => {
+    const silent = new Writable({ write(_chunk, _enc, cb) {
+      cb();
+    } });
+    const rl = createInterface({ input: process.stdin, output: silent, terminal: true });
+    rl.question("", (answer) => {
+      rl.close();
+      process.stderr.write(`
+`);
+      resolve(answer);
+    });
+  });
 }
-async function driveMasterKey(credentials) {
-  const passphrase = drivePassphrase();
+function askVisible(question) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+var CANARY_PLAIN = utf82("crab-drive-verify");
+var CANARY_AAD = utf82("drive-verify");
+function driveKeyPath(accountId) {
+  return join2(CONFIG_DIR, `drive-key-${accountId}.json`);
+}
+function readDriveKeyFile(accountId) {
+  try {
+    return JSON.parse(readFileSync2(driveKeyPath(accountId), "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function loadVerifiedDriveKey(credentials, accountId) {
+  const file = readDriveKeyFile(accountId);
+  if (!file || file.apiBase !== credentials.apiBase || typeof file.masterKey !== "string" || typeof file.canary !== "string") {
+    return null;
+  }
+  try {
+    const key = await importAesKey(b64urlDecode(file.masterKey));
+    await aeadDecrypt(key, sealFromB64url(file.canary), CANARY_AAD);
+    return b64urlDecode(file.masterKey);
+  } catch {
+    forgetDriveKey(accountId);
+    console.error("本机记住的云盘钥匙已失效（可能在别处轮换），请改用口令。");
+    return null;
+  }
+}
+async function storeDriveKey(accountId, apiBase, masterRaw) {
+  const sealed = await aeadEncrypt(await importAesKey(masterRaw), CANARY_PLAIN, CANARY_AAD);
+  mkdirSync2(CONFIG_DIR, { recursive: true });
+  writeFileSync2(driveKeyPath(accountId), `${JSON.stringify({ apiBase, masterKey: b64urlEncode(masterRaw), canary: sealToB64url({ iv: sealed.iv, ciphertext: sealed.ciphertext }), storedAt: Date.now() }, null, 2)}
+`, { mode: 384 });
+}
+function forgetDriveKey(accountId) {
+  rmSync2(driveKeyPath(accountId), { force: true });
+}
+var accountIdMemo;
+async function driveAccountId(credentials) {
+  if (accountIdMemo !== undefined)
+    return accountIdMemo;
+  const res = await api2(credentials.apiBase, "/v1/auth/me", { headers: authHeaders(credentials) });
+  accountIdMemo = res.status === 200 ? res.body.data.account.id : null;
+  return accountIdMemo;
+}
+async function maybeRememberDriveKey(credentials, masterRaw) {
+  if (!process.stdin.isTTY)
+    return;
+  const accountId = await driveAccountId(credentials);
+  const existing = accountId ? readDriveKeyFile(accountId) : null;
+  if (accountId && existing && existing.apiBase === credentials.apiBase && existing.masterKey)
+    return;
+  const answer = await askVisible("记住云盘钥匙到本机？下次免输口令（storage key --forget 清除）[y/N] ");
+  if (answer.trim().toLowerCase() === "y") {
+    await storeDriveKey(accountId, credentials.apiBase, masterRaw);
+    console.log("✓ 已记住云盘钥匙到本机（storage key --forget 可清除）。");
+  }
+}
+async function storageKeyCmd() {
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const accountId = await driveAccountId(credentials);
+  if (!accountId) {
+    console.error("获取账号身份失败（凭证无效？）。");
+    return EXIT_AUTH;
+  }
+  if (hasFlag("--forget")) {
+    const had = readDriveKeyFile(accountId)?.masterKey !== undefined;
+    forgetDriveKey(accountId);
+    console.log(had ? "✓ 已清除本机记住的云盘钥匙，下次操作恢复口令输入。" : "本机没有记住的云盘钥匙。");
+    return 0;
+  }
+  if (hasFlag("--remember")) {
+    const existing = readDriveKeyFile(accountId);
+    if (existing && existing.apiBase === credentials.apiBase && existing.masterKey) {
+      console.log(`本机已记住云盘钥匙：${driveKeyPath(accountId)}`);
+      return 0;
+    }
+    const raw = await driveMasterKeyRaw(credentials, { skipRememberPrompt: true });
+    if (typeof raw === "number")
+      return raw;
+    await storeDriveKey(accountId, credentials.apiBase, raw);
+    console.log(`✓ 已记住云盘钥匙到本机：${driveKeyPath(accountId)}（storage key --forget 清除）`);
+    return 0;
+  }
+  const file = readDriveKeyFile(accountId);
+  if (file && file.apiBase === credentials.apiBase && file.masterKey) {
+    const when = typeof file.storedAt === "number" ? new Date(file.storedAt).toLocaleString() : "未知时间";
+    console.log(`✓ 本机已记住云盘钥匙：${driveKeyPath(accountId)}（记住于 ${when}）`);
+    console.log("  之后 storage 命令免输口令；Web 端轮换口令/恢复码后本钥匙自动失效。");
+    console.log("  storage key --forget 清除；storage key --remember 重新解锁并记住。");
+  } else {
+    console.log("本机未记住云盘钥匙（每次操作需输入口令）。");
+    console.log("  storage key --remember：解锁一次并记住；storage key --forget：清除记录。");
+  }
+  return 0;
+}
+var masterKeyRawMemo = null;
+async function driveMasterKeyRaw(credentials, opts = {}) {
+  if (masterKeyRawMemo)
+    return masterKeyRawMemo;
+  const accountId = await driveAccountId(credentials);
+  if (accountId) {
+    const stored = await loadVerifiedDriveKey(credentials, accountId);
+    if (stored) {
+      const res = await api2(credentials.apiBase, "/v1/storage/keys", { headers: authHeaders(credentials) });
+      if (res.status === 200) {
+        masterKeyRawMemo = stored;
+        return stored;
+      }
+      if (res.status === 404) {
+        forgetDriveKey(accountId);
+      } else {
+        console.error(errorMessage(res.body, "获取云盘密钥失败。"));
+        return exitCodeForApiError(res.body);
+      }
+    }
+  }
+  const passphrase = await drivePassphrase();
   if (!passphrase) {
-    console.error("需要云盘口令：--passphrase <口令> 或环境变量 CRAB_PASSPHRASE。");
+    console.error("需要云盘口令：--passphrase <口令> 或环境变量 CRAB_PASSPHRASE（交互终端会提示输入）。");
     return EXIT_USAGE;
   }
   const res = await api2(credentials.apiBase, "/v1/storage/keys", { headers: authHeaders(credentials) });
@@ -7479,7 +7649,10 @@ async function driveMasterKey(credentials) {
     }
     console.log(`★ 恢复码：${recoveryCode}`);
     console.log("  （口令遗忘时的唯一找回方式；平台无后门，丢失即数据不可解）");
-    return importAesKey(masterRaw);
+    if (!opts.skipRememberPrompt)
+      await maybeRememberDriveKey(credentials, masterRaw);
+    masterKeyRawMemo = masterRaw;
+    return masterRaw;
   }
   if (res.status !== 200) {
     console.error(errorMessage(res.body, "获取云盘密钥失败。"));
@@ -7488,12 +7661,22 @@ async function driveMasterKey(credentials) {
   const keys = res.body.data;
   try {
     const kek = await importAesKey(await deriveKekBits(passphrase, b64urlDecode(keys.kdfSalt), keys.kdfIterations));
-    return await importAesKey(await unwrapKeyBytes(kek, sealFromB64url(keys.wrappedMasterKey.slice(3)), MASTER_AAD));
+    const masterRaw = await unwrapKeyBytes(kek, sealFromB64url(keys.wrappedMasterKey.slice(3)), MASTER_AAD);
+    if (!opts.skipRememberPrompt)
+      await maybeRememberDriveKey(credentials, masterRaw);
+    masterKeyRawMemo = masterRaw;
+    return masterRaw;
   } catch {
     console.error("口令错误。");
     return 1;
   }
 }
+async function driveMasterKey(credentials) {
+  const raw = await driveMasterKeyRaw(credentials);
+  if (typeof raw === "number")
+    return raw;
+  return importAesKey(raw);
+}
 async function storageUploadOne(credentials, filePath) {
   let buf;
   try {
@@ -7637,11 +7820,6 @@ async function storageDownload(token) {
   let bytes = new Uint8Array(await res.arrayBuffer());
   const wrapped = res.headers.get("x-drive-wrapped-key");
   if (wrapped?.startsWith("u1.")) {
-    const passphrase = drivePassphrase();
-    if (!passphrase) {
-      console.error("该文件已加密：--passphrase <口令> 或 CRAB_PASSPHRASE 提供云盘口令后重试。");
-      return EXIT_USAGE;
-    }
     const master = await driveMasterKey(credentials);
     if (typeof master === "number")
       return master;
@@ -7708,13 +7886,20 @@ async function storageTag(token) {
 }
 async function storageCategory(token, value) {
   if (!token || !value) {
-    console.error("用法：crab storage category <id|文件名> <categoryId|none>（分类 id 见 storage categories）");
+    console.error("用法：crab storage category <id|文件名> <分类id|分类名|none>（分类见 storage categories）");
     return EXIT_USAGE;
   }
   const credentials = requireCredentials();
   if (typeof credentials === "number")
     return credentials;
-  const result = await storagePatch(credentials, token, { categoryId: value === "none" ? null : value });
+  let categoryId = null;
+  if (value !== "none") {
+    const resolved = await resolveCategoryId(credentials, value);
+    if (typeof resolved === "number")
+      return resolved;
+    categoryId = resolved;
+  }
+  const result = await storagePatch(credentials, token, { categoryId });
   if (typeof result === "number")
     return result;
   console.log(`✓ 分类已更新：${result.filename}`);
@@ -7732,8 +7917,10 @@ async function storagePublish(token, publish) {
   if (typeof result === "number")
     return result;
   console.log(`✓ ${publish ? "已公开" : "已收回公开"}：${result.filename}`);
-  if (publish)
-    console.log(`  公开链接：${storagePublicUrl(result.id)}`);
+  if (publish) {
+    const base = credentials.apiBase === DEFAULT_API ? undefined : credentials.apiBase;
+    console.log(`  公开链接：${storagePublicUrl(result.id, base)}`);
+  }
   return 0;
 }
 async function storageMove(action, token) {
@@ -7898,28 +8085,116 @@ async function storageCategories() {
     return 0;
   }
   for (const row of rows)
-    console.log(`${row.id}  ${row.name}  (${row.fileCount})`);
+    console.log(`${row.id}  ${row.name}  [${row.color ?? "—"}]  (${row.fileCount})`);
   return 0;
 }
-async function storageMkCat(name) {
+async function resolveCategoryId(credentials, idOrName) {
+  const res = await api2(credentials.apiBase, "/v1/storage/categories", { headers: authHeaders(credentials) });
+  if (res.status !== 200) {
+    console.error(errorMessage(res.body, "获取分类失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  const rows = res.body.data.categories;
+  const byId = rows.find((row) => row.id === idOrName);
+  if (byId)
+    return byId.id;
+  const byName = rows.filter((row) => row.name === idOrName);
+  if (byName.length === 1)
+    return byName[0].id;
+  if (byName.length === 0) {
+    console.error(`分类不存在：${idOrName}（crab storage categories 查看列表）`);
+    return EXIT_NOT_FOUND;
+  }
+  console.error(`分类名重复：${idOrName}，请用 id 指认。`);
+  return EXIT_USAGE;
+}
+function positionalArgs(rest, valuedFlags) {
+  const out = [];
+  for (let i = 0;i < rest.length; i++) {
+    if (valuedFlags.includes(rest[i])) {
+      i++;
+      continue;
+    }
+    if (rest[i].startsWith("--"))
+      continue;
+    out.push(rest[i]);
+  }
+  return out;
+}
+async function storageMkCat(rest) {
+  const name = positionalArgs(rest, ["--color"]).join(" ") || undefined;
   if (!name) {
-    console.error("用法：crab storage mkcat <名称>");
+    console.error("用法：crab storage mkcat <名称> [--color 色]");
     return EXIT_USAGE;
   }
   const credentials = requireCredentials();
   if (typeof credentials === "number")
     return credentials;
+  const color = readFlag("--color");
   const res = await api2(credentials.apiBase, "/v1/storage/categories", {
     method: "POST",
     headers: authHeaders(credentials),
-    body: JSON.stringify({ name })
+    body: JSON.stringify({ name, ...color ? { color } : {} })
   });
   if (res.status !== 200 && res.status !== 201) {
     console.error(errorMessage(res.body, "创建分类失败。"));
     return exitCodeForApiError(res.body);
   }
   const row = res.body.data;
-  console.log(`✓ 已创建分类：${row.name}（id ${row.id}）`);
+  console.log(`✓ 已创建分类：${row.name}（id ${row.id}，颜色 ${row.color ?? "—"}）`);
+  return 0;
+}
+async function storageRenCat(target, rest) {
+  const name = positionalArgs(rest, ["--color"]).join(" ") || undefined;
+  if (!target || !name && !readFlag("--color")) {
+    console.error("用法：crab storage rencat <id|分类名> <新名称> [--color 色]");
+    return EXIT_USAGE;
+  }
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const id = await resolveCategoryId(credentials, target);
+  if (typeof id === "number")
+    return id;
+  const body = {};
+  if (name)
+    body.name = name;
+  const color = readFlag("--color");
+  if (color)
+    body.color = color;
+  const res = await api2(credentials.apiBase, `/v1/storage/categories/${encodeURIComponent(id)}`, {
+    method: "PATCH",
+    headers: authHeaders(credentials),
+    body: JSON.stringify(body)
+  });
+  if (res.status !== 200) {
+    console.error(errorMessage(res.body, "更新分类失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  const row = res.body.data;
+  console.log(`✓ 分类已更新：${row.name}（颜色 ${row.color ?? "—"}）`);
+  return 0;
+}
+async function storageRmCat(target) {
+  if (!target) {
+    console.error("用法：crab storage rmcat <id|分类名>（分类下文件回落未分类，不删文件）");
+    return EXIT_USAGE;
+  }
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const id = await resolveCategoryId(credentials, target);
+  if (typeof id === "number")
+    return id;
+  const res = await api2(credentials.apiBase, `/v1/storage/categories/${encodeURIComponent(id)}`, {
+    method: "DELETE",
+    headers: authHeaders(credentials)
+  });
+  if (res.status !== 200) {
+    console.error(errorMessage(res.body, "删除分类失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  console.log("✓ 分类已删除，其中文件回落未分类。");
   return 0;
 }
 async function storageTags() {
@@ -8053,7 +8328,7 @@ async function collabSpaceCreate(name) {
     return 0;
   }
   console.log(`✓ 独立协作空间已创建（id ${data.spaceId}）`);
-  console.log(`  消耗积分：${fmtCredits(data.chargedCredits)} · --space space:${name} 即可指向它`);
+  console.log(`  消耗：${fmtUsd(data.chargedCredits)} · --space space:${name} 即可指向它`);
   return 0;
 }
 async function collabTasksList() {
@@ -8544,7 +8819,11 @@ switch (command) {
     if (sub === "categories")
       process.exit(await storageCategories());
     if (sub === "mkcat")
-      process.exit(await storageMkCat(args.slice(2).join(" ") || undefined));
+      process.exit(await storageMkCat(args.slice(2)));
+    if (sub === "rencat")
+      process.exit(await storageRenCat(args[2], args.slice(3)));
+    if (sub === "rmcat")
+      process.exit(await storageRmCat(args[2]));
     if (sub === "tags")
       process.exit(await storageTags());
     if (sub === "share")
@@ -8553,8 +8832,10 @@ switch (command) {
       process.exit(await storageShares(args[2]));
     if (sub === "unshare")
       process.exit(await storageUnshare(args[2]));
+    if (sub === "key")
+      process.exit(await storageKeyCmd());
     console.error(sub ? `未知子命令：storage ${sub}
-` : `缺少子命令：storage ls | upload | download | rename | tag | category | publish | unpublish | rm | restore | purge | quota | categories | mkcat | tags | share | shares | unshare
+` : `缺少子命令：storage ls | upload | download | rename | tag | category | publish | unpublish | rm | restore | purge | quota | categories | mkcat | rencat | rmcat | tags | share | shares | unshare | key
 `);
     console.log(usage);
     process.exit(EXIT_USAGE);

package/dist/skills/crabcloud-storage/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: crabcloud-storage
-description: Manage the user's Crab Cloud Drive (云盘 — unified storage for drive uploads, media assets and mail attachments on one quota) through the `crab` CLI — list and filter objects, upload and download files, rename, tag, categorize, publish/unpublish public links, trash/restore/purge, and check the storage quota. Use this skill when the user asks to upload, find, organize, share or clean up files on Crab Cloud ("上传这个文件", "云盘里有什么", "把这个文件公开分享", "看看存储用了多少", "crab storage"), or wants files moved in or out of their drive — even if they never say "crab" or "Crab Cloud" explicitly.
+description: Manage the user's Crab Cloud Drive (云盘 — unified storage for drive uploads, media assets and mail attachments on one quota, with end-to-end encryption) through the `crab` CLI — list and filter objects, upload and download files (including decrypting share links), rename, tag, categorize, publish/unpublish public links, create expiring share links with passcodes, manage the locally remembered encryption key, trash/restore/purge, and check the storage quota. Use this skill when the user asks to upload, find, organize, share or clean up files on Crab Cloud ("上传这个文件", "云盘里有什么", "把这个文件公开分享", "看看存储用了多少", "crab storage"), or wants files moved in or out of their drive — even if they never say "crab" or "Crab Cloud" explicitly.
 ---
 
 # Crab Cloud 云盘（crab storage）
 
 云盘是用户的统一存储：云盘上传 / 素材库 / 邮件附件三来源共用一本 2 GB 容量账；
-属性优先、位置无关——分类（至多一个）+ 标签（AND 检索）代替文件夹。本 skill
-覆盖云盘域的 agent 通道；账号/令牌管理见 `crabcloud` skill，邮箱见
-`crabcloud-mail` skill。
+属性优先、位置无关——分类（至多一个）+ 标签（AND 检索）代替文件夹。files 域
+上传默认端到端加密（服务器只有包裹态密钥，明文密钥只在本机）。本 skill 覆盖
+云盘域的 agent 通道；账号/令牌管理见 `crabcloud` skill，邮箱见 `crabcloud-mail`
+skill。
 
 ## 第一步：确认可用
 
@@ -29,22 +30,27 @@ description: Manage the user's Crab Cloud Drive (云盘 — unified storage for
 
 | 用户意图 | 命令 |
 |---|---|
-| 云盘里有什么 | `crab storage ls`（按时间倒序，默认 30 条） |
-| 找文件 | `crab storage ls --q 关键字`（文件名匹配；可叠 `--source files\|media\|mail`、`--type doc\|image\|video\|archive\|code`、`--tag a,b`、`--shared`、`--recent`） |
+| 云盘里有什么 | `crab storage ls`（按时间倒序，默认 30 条；`--limit` / `--offset` 翻页） |
+| 找文件 | `crab storage ls --q 关键字`（文件名匹配；可叠 `--source files\|media\|mail`、`--type doc\|image\|video\|archive\|code`、`--category 分类id\|none`、`--tag a,b`、`--shared`、`--recent`、`--message-id <id>`） |
 | 看回收站 | `crab storage ls --trash` |
-| 上传文件 | `crab storage upload <路径...>`（多文件串行；直传优先，自动回退中转） |
-| 下载文件 | `crab storage download <id\|文件名> [-o 输出路径]`（默认按原文件名存当前目录） |
+| 上传文件 | `crab storage upload <路径...>`（多文件串行；直传优先，自动回退中转；默认端到端加密——口令三来源见下节，首次使用自动初始化并打印一次性恢复码） |
+| 下载文件 | `crab storage download <id\|文件名\|分享链接> [-o 输出路径] [--passcode 提取码]`（默认按原文件名存当前目录；**凭完整分享链接可免登录下载并本地解密**——`#` 后是密钥片段，这是 agent→agent 的主通道；带提取码的分享加 `--passcode`） |
 | 改名 | `crab storage rename <id\|文件名> <新名称>` |
 | 加/删标签 | `crab storage tag <id\|文件名> --add a,b [--remove c,d]` |
-| 归类 / 建分类 | `crab storage category <id\|文件名> <categoryId\|none>`；`crab storage mkcat <名称>`；分类 id 见 `crab storage categories` |
+| 归类 | `crab storage category <id\|文件名> <分类id\|分类名\|none>`（分类名唯一命中即解析） |
+| 建分类 | `crab storage mkcat <名称> [--color 色]` |
+| 改分类名/颜色 | `crab storage rencat <id\|分类名> <新名称> [--color 色]` |
+| 删分类 | `crab storage rmcat <id\|分类名>`（分类下文件回落未分类，不删文件） |
 | 公开分享 | `crab storage publish <id\|文件名>`（打印公开直链；收回用 `unpublish`） |
 | 可控分享（有效期/提取码/撤销） | `crab storage share <id\|文件名> [--expires 7\|30\|90\|forever] [--passcode 提取码]`（打印完整分享链接；加密对象链接自带 `#` 密钥片段）；列表 `crab storage shares <id\|文件名>`、撤销 `crab storage unshare <shareId>` |
+| 云盘钥匙管理 | `crab storage key`（查状态）/ `--remember`（解锁一次并记住，之后免口令）/ `--forget`（清除）——见下节 |
 | 删除 | `crab storage rm <id\|文件名>`（进回收站，7 天后自动清理）→ `restore` 恢复 / `purge` 彻底删除 |
 | 看水位 | `crab storage quota`（三来源分项 + 回收站占用 + 对象计数） |
 
 `<id|文件名>`：文件名全库精确唯一命中时自动解析为 id（回收站内同样可解析，
 restore/purge 直接用文件名即可）；命中多个或查不到时按字面当 id 用——拿不准
-先 `crab storage ls --q <关键字>` 核对再操作。
+先 `crab storage ls --q <关键字>` 核对再操作。分类指认同款：id 精确命中优先，
+名称唯一命中其次（`rencat` / `rmcat` / `--category` 都吃 `<id|分类名>`）。
 
 ## 机器可读输出
 
@@ -53,7 +59,26 @@ restore/purge 直接用文件名即可）；命中多个或查不到时按字面
 - `storage ls --json` → `{ objects: [...], nextOffset, total }`，条目含
   `id / source / filename / mimeType / sizeBytes / categoryId / tags / isPublic / createdAt`；
 - `storage quota --json` → `{ usedBytes, quotaBytes, bySource: { files, media, mail }, trashBytes, counts }`；
-- `upload` / `categories` / `tags` 的 `--json` 同构（单对象 / 分类数组 / 标签数组）。
+- `upload` / `categories` / `tags` / `shares` 的 `--json` 同构（单对象 / 分类数组 /
+  标签数组 / 分享数组）。
+
+## 云盘口令与本机钥匙
+
+files 域是端到端加密：服务器只有口令包裹态的主密钥，**明文密钥只存在于用户
+本机**——CLI 不可能也不允许向服务器索取。涉及加密对象的命令（upload /
+download / share 加密文件）需要云盘口令，来源优先级：
+
+1. `--passphrase <口令>`（flag）
+2. 环境变量 `CRAB_PASSPHRASE`（**Agent/脚本推荐**——非交互终端不会弹提问，
+   缺失时明确报错）
+3. 交互终端（TTY）隐藏输入提问（人不经管道跑 CLI 时的默认体验）
+
+本机钥匙（`crab storage key`）：口令解锁成功后可把**主密钥**（非口令）记住到
+本机 `~/.config/crabcloud/drive-key-<账号id>.json`（0600，按账号+环境隔离），
+之后所有命令免口令——等同 Web 端「记住此设备」。`--remember` 主动记住、
+`--forget` 清除、默认查状态；Web 端轮换口令/恢复码后本机钥匙自动验签失效并
+回落口令，无需手工干预。Agent 视角：**用户没让你动钥匙设置时不要主动调
+`storage key`**；用户口令遗忘是恢复码流程（Web 端），CLI 侧无法代找回。
 
 ## 纪律
 
@@ -61,7 +86,11 @@ restore/purge 直接用文件名即可）；命中多个或查不到时按字面
   确认后再执行；收回用 `unpublish`（已缓存浏览器至多 5 分钟内失效）。
 - **share 是可控分享**：默认 7 天有效、可选提取码、随时 `unshare` 撤销；加密
   对象的分享链接自带解密钥匙（`#` 后缀）——泄露链接即泄露文件，外发前向
-  用户复述有效期与提取码设置，确认后再执行。
+  用户复述有效期与提取码设置，确认后再执行。收件人在浏览器打开加密分享链接
+  会看到内联解密落地页（图片/视频/音频/PDF/文本直接预览，其余类型仅下载）。
+- **提取码错误重试有服务端限流**：同一链接+来源 IP 错误次数超限返回 429
+  （退出码 1，消息「尝试过于频繁」）——**不要程序化暴力重试**，如实转述用户
+  等待即可；凭链接下载时提取码用 `--passcode` 正确携带。
 - **purge 是彻底删除**，不可恢复；用户没明说「彻底删除」时一律用 `rm`
   （回收站保留 7 天可找回）。
 - 邮件附件与用户上传同账：水位告急时用 `quota` 分项定位来源再建议清理。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crabcloud/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Crab Cloud CLI (crab) — agent-first entry to your personal cloud, with skills bundled for Claude Code / Codex / ZCode.",
   "bin": {