@crabcloud/cli 0.1.8 → 0.1.9

package/dist/crab.js

@@ -5869,12 +5869,23 @@ var adminCreditPackInput = object({
   title: string2().trim().min(1).max(100),
   credits: number2().int().positive().max(1e7),
   priceCents: number2().int().positive(),
-  currency: string2().trim().length(3).default("CNY"),
+  currency: string2().trim().length(3).default("USD"),
   sort: number2().int().min(0).max(1e4).default(0)
 });
 var adminCreditPackUpdateInput = adminCreditPackInput.partial().extend({
   status: _enum(creditPackStatuses).optional()
 });
+var adminPricingOverridesInput = object({
+  overrides: record(string2().trim().min(1).max(100), union([number2().int().positive().max(1e8), _null3()]))
+});
+var adminPlanTierStatuses = ["active", "hidden"];
+var adminPlanTierUpdateInput = object({
+  name: string2().trim().min(1).max(50).optional(),
+  priceCents: number2().int().min(0).max(1e8).nullable().optional(),
+  monthlyCredits: number2().int().min(0).max(1e8).optional(),
+  quotaJson: record(string2(), unknown()).optional(),
+  status: _enum(adminPlanTierStatuses).optional()
+});
 var giftFulfillments = ["stock", "webhook"];
 var giftMerchantStatuses = ["active", "disabled"];
 var giftProductStatuses = ["draft", "live", "delisted"];
@@ -5980,6 +5991,57 @@ var contactQueryInput = object({
   offset: number2().int().min(0).default(0)
 });
 
+// ../../packages/cloudkit/src/crypto.ts
+var enc = new TextEncoder;
+var b64urlEncode = (bytes) => {
+  let s = "";
+  for (const b of bytes)
+    s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+var b64urlDecode = (s) => Uint8Array.from(atob(s.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0));
+function randomCode(length = 6) {
+  const alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+  return Array.from(crypto.getRandomValues(new Uint8Array(length)), (byte) => alphabet[byte % alphabet.length]).join("");
+}
+
+// ../../packages/cloudkit/src/secretbox.ts
+var enc2 = new TextEncoder;
+var utf8 = (s) => enc2.encode(s);
+var DEFAULT_KEK_ITERATIONS = 210000;
+async function deriveKekBits(password, salt, iterations = DEFAULT_KEK_ITERATIONS) {
+  const key = await crypto.subtle.importKey("raw", utf8(password), "PBKDF2", false, ["deriveBits"]);
+  return new Uint8Array(await crypto.subtle.deriveBits({ name: "PBKDF2", hash: "SHA-256", salt, iterations }, key, 256));
+}
+async function importAesKey(raw, usages = ["encrypt", "decrypt"]) {
+  return crypto.subtle.importKey("raw", raw, "AES-GCM", false, usages);
+}
+function randomKeyBytes(length = 32) {
+  return crypto.getRandomValues(new Uint8Array(length));
+}
+async function aeadEncrypt(key, plaintext, aad) {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const params = aad ? { name: "AES-GCM", iv, additionalData: aad } : { name: "AES-GCM", iv };
+  const ciphertext = await crypto.subtle.encrypt(params, key, plaintext);
+  return { iv, ciphertext: new Uint8Array(ciphertext) };
+}
+async function aeadDecrypt(key, sealed, aad) {
+  const params = aad ? { name: "AES-GCM", iv: sealed.iv, additionalData: aad } : { name: "AES-GCM", iv: sealed.iv };
+  return new Uint8Array(await crypto.subtle.decrypt(params, key, sealed.ciphertext));
+}
+async function unwrapKeyBytes(kek, sealed, aad) {
+  return aeadDecrypt(kek, sealed, aad);
+}
+function sealToB64url(sealed) {
+  return `${b64urlEncode(sealed.iv)}.${b64urlEncode(sealed.ciphertext)}`;
+}
+function sealFromB64url(s) {
+  const [iv, ct] = s.split(".");
+  if (!iv || !ct)
+    throw new Error("invalid sealed payload");
+  return { iv: b64urlDecode(iv), ciphertext: b64urlDecode(ct) };
+}
+
 // ../../packages/skills/src/install.ts
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -6268,9 +6330,14 @@ var usage = `crab — Crab Cloud CLI（Agent-first 入口）
                        列出邮件（cursor 分页契约与 Web 工作台一致）
   mail read <id> [--json]            读取邮件正文（自动置已读）
   mail search <query> [--json]       全文搜索（主题/发件人/收件人/正文）
-  mail send --to a@x.cc,b@y.cn [--cc c@z.io] --subject "..." --body "..." | --body-file <path>
-       [--in-reply-to <message-id>]      回信线程锚点（原信 RFC Message-ID，crab mail read 可见）
-                       发送邮件：平台内（@crabcloud.cc）免费，外部出站 2 积分/封
+  mail send --to a@x.cc|联系人名,b@y.cn [--cc c@z.io] --subject "..." --body "..." | --body-file <path>
+       [--attach <云盘id|文件名>,...] [--in-reply-to <message-id>]
+                                         回信线程锚点（原信 RFC Message-ID，crab mail read 可见）
+                       发送邮件：不含 @ 的收件人按联系人簿解析（备注名/地址精确
+                       命中采用，多候选报错列出）；--attach 引用云盘已有对象
+                       （id 或文件名精确唯一命中，未绑信对象，≤10 个，大文件
+                       自动转下载链接）；平台内（@crabcloud.cc）免费，外部出站
+                       2 积分/封
   mail archive|trash|delete <id>     移夹 / 废纸篓 / 彻底删除（delete 不可恢复）
   contacts list [query] [--offset N] [--json]     列出联系人（地址前缀/显示名匹配）
   contacts add <address> [--name 名] [--note 备注] [--json]
@@ -6281,7 +6348,7 @@ var usage = `crab — Crab Cloud CLI（Agent-first 入口）
                                      我邀请的人（直接下级 + 间接计数）
   storage ls [--q 关键字] [--source files|media|mail] [--category <id|none>]
                [--type doc|image|video|archive|code] [--tag a,b] [--trash]
-               [--shared] [--recent] [--limit N] [--offset N] [--json]
+               [--shared] [--recent] [--message-id <id>] [--limit N] [--offset N] [--json]
                                      列出云盘对象（跨来源统一视图，能力与 Web 云盘一致）
   storage upload <file...> [--json]  上传一个或多个文件（直传优先，自动回退中转）
   storage download <id|文件名> [-o 输出路径]
@@ -6296,6 +6363,11 @@ var usage = `crab — Crab Cloud CLI（Agent-first 入口）
   storage rm|restore|purge <id|文件名>
                                      回收站 / 恢复 / 彻底删除（purge 不可恢复）
   storage quota [--json]             存储水位（统一容量账：文件/素材/邮件附件一本账）
+  storage share <id|文件名> [--expires 7|30|90|forever] [--passcode 提取码]
+                       创建分享链接（加密文件链接自带解密钥匙 #fragment）
+  storage shares <id|文件名> [--json]
+                                     该文件的分享链接列表（状态/下载计数）
+  storage unshare <shareId>          撤销分享
   storage categories [--json]        分类列表
   storage mkcat <名称>               新建分类
   storage tags [--json]              标签汇总
@@ -6401,7 +6473,7 @@ async function whoami() {
   if (subscription)
     console.log(`  订阅: ${subscription.tier_name}`);
   if (credits !== undefined)
-    console.log(`  积分余额: ${credits}`);
+    console.log(`  积分余额: $${(credits / 100).toFixed(2)} (${credits} credit_cents)`);
   if (apps?.length)
     console.log(`  已启用应用: ${apps.map((a) => a.title).join("、")}`);
   return 0;
@@ -6530,6 +6602,13 @@ async function mailRead(id) {
     console.log(`  回复: ${mail.inReplyTo}`);
   console.log("");
   console.log(mail.bodyText);
+  if (mail.attachments.length > 0) {
+    console.log("");
+    console.log("附件:");
+    for (const att of mail.attachments) {
+      console.log(`  ${att.id}  ${att.filename}  ${att.mimeType}  ${formatBytesCli(att.sizeBytes)}`);
+    }
+  }
   if (mail.actors.length > 0) {
     console.log("");
     console.log("操作记录:");
@@ -6565,15 +6644,63 @@ async function mailSearch(query) {
     printMailRow(mail);
   return 0;
 }
+async function resolveRecipients(credentials, tokens) {
+  const resolved = [];
+  for (const token of tokens) {
+    if (token.includes("@")) {
+      resolved.push(token);
+      continue;
+    }
+    const params = new URLSearchParams({ query: token, limit: "50" });
+    const res = await api2(credentials.apiBase, `/v1/contacts?${params}`, { headers: authHeaders(credentials) });
+    if (res.status !== 200) {
+      console.error(errorMessage(res.body, "查询联系人失败。"));
+      return null;
+    }
+    const items = res.body.data.items;
+    const lowered = token.toLowerCase();
+    const exact = items.filter((c) => c.address.toLowerCase() === lowered || (c.displayName ?? "").toLowerCase() === lowered);
+    if (exact.length === 1) {
+      resolved.push(exact[0].address);
+      continue;
+    }
+    if (exact.length > 1) {
+      console.error(`「${token}」匹配到多个联系人，请改用完整地址：`);
+      for (const c of exact.slice(0, 5))
+        console.error(`  ${contactDisplayName(c)} <${c.address}>`);
+      return null;
+    }
+    if (items.length === 1) {
+      console.error(`「${token}」→ ${contactDisplayName(items[0])} <${items[0].address}>`);
+      resolved.push(items[0].address);
+      continue;
+    }
+    console.error(`「${token}」没有唯一命中的联系人。`);
+    if (items.length > 0) {
+      console.error("相近候选：");
+      for (const c of items.slice(0, 5))
+        console.error(`  ${contactDisplayName(c)} <${c.address}>`);
+    } else {
+      console.error("联系人簿没有相近条目（可先 crab contacts list 查看）。");
+    }
+    return null;
+  }
+  return resolved;
+}
 async function mailSend() {
-  const to = (readFlag("--to") ?? "").split(",").map((x) => x.trim()).filter(Boolean);
-  const cc = (readFlag("--cc") ?? "").split(",").map((x) => x.trim()).filter(Boolean);
+  const toRaw = (readFlag("--to") ?? "").split(",").map((x) => x.trim()).filter(Boolean);
+  const ccRaw = (readFlag("--cc") ?? "").split(",").map((x) => x.trim()).filter(Boolean);
+  const attachRaw = (readFlag("--attach") ?? "").split(",").map((x) => x.trim()).filter(Boolean);
   const subject = readFlag("--subject") ?? "";
   const bodyFlag = readFlag("--body");
   const bodyFile = readFlag("--body-file");
   const inReplyTo = readFlag("--in-reply-to") ?? undefined;
-  if (to.length === 0 || !subject || !bodyFlag && !bodyFile) {
-    console.error('用法：crab mail send --to a@x.cc[,b@y.cn] [--cc c@z.io] --subject "..." --body "..." | --body-file <path> [--in-reply-to <message-id>]');
+  if (toRaw.length === 0 || !subject || !bodyFlag && !bodyFile) {
+    console.error('用法：crab mail send --to a@x.cc|联系人名[,b@y.cn] [--cc c@z.io] --subject "..." --body "..." | --body-file <path> [--attach <云盘id|文件名>,...] [--in-reply-to <message-id>]');
+    return EXIT_USAGE;
+  }
+  if (attachRaw.length > 10) {
+    console.error("附件最多 10 个。");
     return EXIT_USAGE;
   }
   let body = bodyFlag ?? "";
@@ -6588,10 +6715,29 @@ async function mailSend() {
   const credentials = requireCredentials();
   if (typeof credentials === "number")
     return credentials;
+  const to = await resolveRecipients(credentials, toRaw);
+  if (to === null)
+    return 1;
+  const cc = ccRaw.length > 0 ? await resolveRecipients(credentials, ccRaw) : [];
+  if (cc === null)
+    return 1;
+  const attachmentIds = [];
+  for (const token of attachRaw) {
+    const hit = await resolveStorageObject(credentials, token);
+    if (typeof hit === "number")
+      return hit;
+    if (typeof hit === "object" && hit.isEncrypted) {
+      console.error(`「${token}」是端到端加密文件，暂不能作为邮件附件发送（服务端无法解密）。`);
+      return EXIT_USAGE;
+    }
+    const id = typeof hit === "object" ? hit.id : hit;
+    if (!attachmentIds.includes(id))
+      attachmentIds.push(id);
+  }
   const res = await api2(credentials.apiBase, "/v1/mail/messages", {
     method: "POST",
     headers: authHeaders(credentials),
-    body: JSON.stringify({ to, cc, subject, body, ...inReplyTo ? { inReplyTo } : {} })
+    body: JSON.stringify({ to, cc, subject, body, ...inReplyTo ? { inReplyTo } : {}, ...attachmentIds.length > 0 ? { attachmentIds } : {} })
   });
   if (res.status !== 200 && res.status !== 201) {
     console.error(errorMessage(res.body, "发送失败。"));
@@ -6603,8 +6749,10 @@ async function mailSend() {
     return 0;
   }
   console.log(`✓ 已发送（id ${result.message.id}）`);
+  if (attachmentIds.length > 0)
+    console.log(`  附件 ${attachmentIds.length} 个（云盘引用，不复制）`);
   if (result.chargedCredits > 0)
-    console.log(`  消耗积分：${result.chargedCredits}`);
+    console.log(`  消耗积分：$${(result.chargedCredits / 100).toFixed(2)}（${result.chargedCredits} credit_cents）`);
   if (result.failedExternal > 0)
     console.log(`  ⚠ ${result.failedExternal} 个外部收件人发送失败，对应积分已退回`);
   return 0;
@@ -6824,11 +6972,12 @@ function formatBytesCli(n) {
 function printStorageRow(o) {
   const flags = [
     o.source !== "files" ? o.source === "media" ? "素材" : "邮件附件" : null,
+    o.isEncrypted ? "加密" : null,
     o.isPublic ? "公开" : null
   ].filter(Boolean);
   console.log(`${o.id}  ${o.filename}  ${formatBytesCli(o.sizeBytes)}  ${formatTime(o.createdAt)}${flags.length > 0 ? `  [${flags.join(" · ")}]` : ""}`);
 }
-async function resolveStorageId(credentials, token) {
+async function resolveStorageObject(credentials, token) {
   for (const trash of [false, true]) {
     const params = new URLSearchParams({ limit: "100", q: token });
     if (trash)
@@ -6846,10 +6995,16 @@ async function resolveStorageId(credentials, token) {
       return EXIT_USAGE;
     }
     if (exact.length === 1)
-      return exact[0].id;
+      return exact[0];
   }
   return token;
 }
+async function resolveStorageId(credentials, token) {
+  const hit = await resolveStorageObject(credentials, token);
+  if (typeof hit === "string" || typeof hit === "number")
+    return hit;
+  return hit.id;
+}
 async function storageList() {
   const credentials = requireCredentials();
   if (typeof credentials === "number")
@@ -6891,6 +7046,9 @@ async function storageList() {
   const q = readFlag("--q");
   if (q)
     params.set("q", q);
+  const messageId = readFlag("--message-id");
+  if (messageId)
+    params.set("messageId", messageId);
   const res = await api2(credentials.apiBase, `/v1/storage?${params}`, { headers: authHeaders(credentials) });
   if (res.status !== 200) {
     console.error(errorMessage(res.body, "获取云盘列表失败。"));
@@ -6907,10 +7065,65 @@ async function storageList() {
   }
   for (const object of page.objects)
     printStorageRow(object);
+  console.log(`共 ${page.total} 条`);
   if (page.nextOffset !== null)
     console.log(`（还有更多：storage ls --offset ${page.nextOffset}）`);
   return 0;
 }
+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;
+}
+async function driveMasterKey(credentials) {
+  const passphrase = drivePassphrase();
+  if (!passphrase) {
+    console.error("需要云盘口令：--passphrase <口令> 或环境变量 CRAB_PASSPHRASE。");
+    return EXIT_USAGE;
+  }
+  const res = await api2(credentials.apiBase, "/v1/storage/keys", { headers: authHeaders(credentials) });
+  if (res.status === 404) {
+    console.error("云盘口令尚未设置——正在初始化（恢复码只显示一次，请立即抄写）：");
+    const salt = b64urlEncode(randomKeyBytes(16));
+    const masterRaw = randomKeyBytes(32);
+    const recoveryCode = randomCode(16);
+    const kek = await importAesKey(await deriveKekBits(passphrase, b64urlDecode(salt), KEK_ITERATIONS));
+    const recoveryKek = await importAesKey(await deriveKekBits(recoveryCode, b64urlDecode(salt), KEK_ITERATIONS));
+    const wrapped = await aeadEncrypt(kek, masterRaw, MASTER_AAD);
+    const recoveryWrapped = await aeadEncrypt(recoveryKek, masterRaw, MASTER_AAD);
+    const put = await api2(credentials.apiBase, "/v1/storage/keys", {
+      method: "PUT",
+      headers: authHeaders(credentials),
+      body: JSON.stringify({
+        kdfSalt: salt,
+        kdfIterations: KEK_ITERATIONS,
+        wrappedMasterKey: `u1.${sealToB64url({ iv: wrapped.iv, ciphertext: wrapped.ciphertext })}`,
+        recoveryWrappedMasterKey: `r1.${sealToB64url({ iv: recoveryWrapped.iv, ciphertext: recoveryWrapped.ciphertext })}`
+      })
+    });
+    if (put.status !== 200 && put.status !== 201) {
+      console.error(errorMessage(put.body, "初始化云盘口令失败。"));
+      return exitCodeForApiError(put.body);
+    }
+    console.log(`★ 恢复码：${recoveryCode}`);
+    console.log("  （口令遗忘时的唯一找回方式；平台无后门，丢失即数据不可解）");
+    return importAesKey(masterRaw);
+  }
+  if (res.status !== 200) {
+    console.error(errorMessage(res.body, "获取云盘密钥失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  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));
+  } catch {
+    console.error("口令错误。");
+    return 1;
+  }
+}
 async function storageUploadOne(credentials, filePath) {
   let buf;
   try {
@@ -6921,14 +7134,22 @@ async function storageUploadOne(credentials, filePath) {
   }
   const filename = basename(filePath);
   const mimeType = mimeFor(filename);
+  const master = await driveMasterKey(credentials);
+  if (typeof master === "number")
+    return master;
+  const dataKey = randomKeyBytes(32);
+  const sealed = await aeadEncrypt(await importAesKey(dataKey), new Uint8Array(buf), DATA_AAD);
+  const cipher = new Uint8Array([...sealed.iv, ...sealed.ciphertext]);
+  const wrapped = await aeadEncrypt(master, dataKey, DATA_AAD);
+  const wrappedDataKey = `u1.${sealToB64url({ iv: wrapped.iv, ciphertext: wrapped.ciphertext })}`;
   const presign = await api2(credentials.apiBase, "/v1/storage/presign", {
     method: "POST",
     headers: authHeaders(credentials),
-    body: JSON.stringify({ filename, mimeType, sizeBytes: buf.byteLength })
+    body: JSON.stringify({ filename, mimeType, sizeBytes: cipher.byteLength, enc: true })
   });
   if (presign.status === 200) {
     const { fileId, uploadUrl } = presign.body.data;
-    const put = await fetch(uploadUrl, { method: "PUT", body: new Uint8Array(buf), headers: { "content-type": mimeType } });
+    const put = await fetch(uploadUrl, { method: "PUT", body: cipher, headers: { "content-type": mimeType } });
     if (!put.ok) {
       console.error(`直传失败（${put.status}）：${filename}`);
       return 1;
@@ -6936,7 +7157,7 @@ async function storageUploadOne(credentials, filePath) {
     const complete = await api2(credentials.apiBase, `/v1/storage/${encodeURIComponent(fileId)}/complete`, {
       method: "POST",
       headers: authHeaders(credentials),
-      body: "{}"
+      body: JSON.stringify({ isEncrypted: true, wrappedDataKey })
     });
     if (complete.status !== 200 && complete.status !== 201) {
       console.error(errorMessage(complete.body, `记账失败：${filename}`));
@@ -6946,12 +7167,14 @@ async function storageUploadOne(credentials, filePath) {
     if (hasFlag("--json"))
       console.log(JSON.stringify(object, null, 2));
     else
-      console.log(`✓ 已上传：${object.filename}（id ${object.id}）`);
+      console.log(`✓ 已上传（已加密）：${object.filename}（id ${object.id}）`);
     return 0;
   }
   if (presign.body?.error?.code === "presign_unavailable") {
     const form = new FormData;
-    form.append("file", new Blob([new Uint8Array(buf)], { type: mimeType }), filename);
+    form.append("file", new Blob([cipher], { type: mimeType }), filename);
+    form.append("enc", "1");
+    form.append("wrappedDataKey", wrappedDataKey);
     const res = await fetch(`${credentials.apiBase}/v1/storage`, {
       method: "POST",
       headers: authHeaders(credentials),
@@ -6965,16 +7188,24 @@ async function storageUploadOne(credentials, filePath) {
     if (hasFlag("--json"))
       console.log(JSON.stringify(body.data, null, 2));
     else
-      console.log(`✓ 已上传：${body.data?.filename}（id ${body.data?.id}）`);
+      console.log(`✓ 已上传（已加密）：${body.data?.filename}（id ${body.data?.id}）`);
     return 0;
   }
   console.error(errorMessage(presign.body, `上传失败：${filename}`));
   return exitCodeForApiError(presign.body);
 }
 async function storageUpload(paths) {
-  const files = paths.filter((p) => !p.startsWith("--"));
+  const files = [];
+  for (let i = 0;i < paths.length; i++) {
+    if (paths[i].startsWith("--")) {
+      if (paths[i] === "--passphrase")
+        i++;
+      continue;
+    }
+    files.push(paths[i]);
+  }
   if (files.length === 0) {
-    console.error("用法：crab storage upload <file...> [--json]");
+    console.error("用法：crab storage upload <file...> [--passphrase 口令] [--json]");
     return EXIT_USAGE;
   }
   const credentials = requireCredentials();
@@ -6992,9 +7223,33 @@ async function storageUpload(paths) {
 }
 async function storageDownload(token) {
   if (!token) {
-    console.error("用法：crab storage download <id|文件名> [-o 输出路径]");
+    console.error("用法：crab storage download <id|文件名|分享链接> [-o 输出路径] [--passphrase 口令] [--passcode 提取码]");
     return EXIT_USAGE;
   }
+  const urlMatch = token.match(/\/s\/([0-9a-f]{64})(?:#([A-Za-z0-9_-]+))?$/);
+  const shareToken = urlMatch?.[1];
+  const fragment = urlMatch?.[2];
+  if (shareToken) {
+    const apiBase = process.env.CRAB_API ?? readFlag("--api") ?? DEFAULT_API;
+    const passcode = readFlag("--passcode");
+    const url = `${apiBase}/s/${shareToken}${passcode ? `?passcode=${encodeURIComponent(passcode)}` : ""}`;
+    const res = await fetch(url);
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      console.error(errorMessage(body, "下载失败。"));
+      return exitCodeForApiError(body);
+    }
+    let bytes = new Uint8Array(await res.arrayBuffer());
+    if (fragment) {
+      bytes = await aeadDecrypt(await importAesKey(b64urlDecode(fragment)), { iv: bytes.slice(0, 12), ciphertext: bytes.slice(12) }, DATA_AAD);
+    }
+    const disposition = res.headers.get("content-disposition") ?? "";
+    const m = disposition.match(/filename\*=UTF-8''([^;]+)/);
+    const out = readFlag("-o") ?? readFlag("--out") ?? (m ? decodeURIComponent(m[1]) : `${shareToken}.bin`);
+    writeFileSync2(out, Buffer.from(bytes));
+    console.log(`✓ 已下载${fragment ? "并解密" : ""}：${out}（${formatBytesCli(bytes.byteLength)}）`);
+    return 0;
+  }
   const credentials = requireCredentials();
   if (typeof credentials === "number")
     return credentials;
@@ -7009,12 +7264,26 @@ async function storageDownload(token) {
     console.error(errorMessage(body, "下载失败。"));
     return exitCodeForApiError(body);
   }
+  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;
+    const dataKey = await unwrapKeyBytes(master, sealFromB64url(wrapped.slice(3)), DATA_AAD);
+    bytes = await aeadDecrypt(await importAesKey(dataKey), { iv: bytes.slice(0, 12), ciphertext: bytes.slice(12) }, DATA_AAD);
+  }
   const disposition = res.headers.get("content-disposition") ?? "";
   const match = disposition.match(/filename\*=UTF-8''([^;]+)/);
   const fallbackName = match ? decodeURIComponent(match[1]) : `${id}.bin`;
   const out = readFlag("-o") ?? readFlag("--out") ?? fallbackName;
-  writeFileSync2(out, Buffer.from(await res.arrayBuffer()));
-  console.log(`✓ 已下载：${out}（${formatBytesCli(Number(res.headers.get("content-length") ?? 0))}）`);
+  writeFileSync2(out, Buffer.from(bytes));
+  console.log(`✓ 已下载：${out}（${formatBytesCli(bytes.byteLength)}）`);
   return 0;
 }
 async function storagePatch(credentials, token, patch) {
@@ -7116,6 +7385,110 @@ async function storageMove(action, token) {
   console.log(`✓ ${action === "rm" ? "已移入回收站（7 天后自动清理）" : action === "restore" ? "已恢复" : "已彻底删除"}（${id}）`);
   return 0;
 }
+async function storageShareCmd(token) {
+  if (!token) {
+    console.error("用法：crab storage share <id|文件名> [--expires 7|30|90|forever] [--passcode 提取码]");
+    return EXIT_USAGE;
+  }
+  const expires = readFlag("--expires") ?? "7";
+  const passcode = readFlag("--passcode");
+  if (!["7", "30", "90", "forever"].includes(expires) || passcode !== undefined && !/^[A-Za-z0-9]{4,8}$/.test(passcode)) {
+    console.error("无效的 --expires / --passcode 参数。");
+    return EXIT_USAGE;
+  }
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const hit = await resolveStorageObject(credentials, token);
+  if (typeof hit === "number")
+    return hit;
+  const id = typeof hit === "object" ? hit.id : hit;
+  const needMaster = typeof hit === "object" && hit.isEncrypted === true && (hit.wrappedDataKey ?? "").startsWith("u1.");
+  const master = needMaster ? await driveMasterKey(credentials) : null;
+  if (needMaster && typeof master === "number")
+    return master;
+  const res = await api2(credentials.apiBase, `/v1/storage/${encodeURIComponent(id)}/share`, {
+    method: "POST",
+    headers: authHeaders(credentials),
+    body: JSON.stringify({ expires, ...passcode ? { passcode } : {} })
+  });
+  if (res.status !== 200 && res.status !== 201) {
+    console.error(errorMessage(res.body, "创建分享失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  const data = res.body.data;
+  let link = data.shareUrl;
+  if (data.isEncrypted && data.wrappedDataKey) {
+    const masterKey = master ?? await driveMasterKey(credentials);
+    if (typeof masterKey === "number") {
+      await api2(credentials.apiBase, `/v1/storage/shares/${encodeURIComponent(data.share.id)}`, {
+        method: "DELETE",
+        headers: authHeaders(credentials)
+      }).catch(() => null);
+      console.error("该文件是端到端加密文件，需要云盘口令解出分享钥匙：--passphrase <口令> 或 CRAB_PASSPHRASE（本次分享已撤销，未留孤儿链接）。");
+      return EXIT_USAGE;
+    }
+    const dataKey = await unwrapKeyBytes(masterKey, sealFromB64url(data.wrappedDataKey.slice(3)), DATA_AAD);
+    link = `${link}#${b64urlEncode(dataKey)}`;
+  }
+  console.log(`✓ 分享链接已创建（${expires === "forever" ? "永久" : `${expires} 天`}有效）：`);
+  console.log(`  ${link}`);
+  if (data.share.hasPasscode)
+    console.log("  （已设提取码，接收方需携带）");
+  if (data.isEncrypted)
+    console.log("  （链接自带解密钥匙，泄露即泄露文件——请走可信渠道传递）");
+  return 0;
+}
+async function storageShares(token) {
+  if (!token) {
+    console.error("用法：crab storage shares <id|文件名>");
+    return EXIT_USAGE;
+  }
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const id = await resolveStorageId(credentials, token);
+  if (typeof id === "number")
+    return id;
+  const res = await api2(credentials.apiBase, `/v1/storage/${encodeURIComponent(id)}/shares`, { headers: authHeaders(credentials) });
+  if (res.status !== 200) {
+    console.error(errorMessage(res.body, "获取分享列表失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  const rows = res.body.data.shares;
+  if (hasFlag("--json")) {
+    console.log(JSON.stringify(rows, null, 2));
+    return 0;
+  }
+  if (rows.length === 0) {
+    console.log("该文件还没有分享链接。");
+    return 0;
+  }
+  for (const s of rows) {
+    const state = s.revokedAt ? "已撤销" : s.expiresAt !== null && s.expiresAt <= Date.now() ? "已过期" : "生效中";
+    console.log(`${s.id}  …${s.token.slice(-12)}  ${state}  下载 ${s.downloadCount} 次  ${formatTime(s.createdAt)}${s.hasPasscode ? "  [提取码]" : ""}`);
+  }
+  return 0;
+}
+async function storageUnshare(shareId) {
+  if (!shareId) {
+    console.error("用法：crab storage unshare <shareId>（id 见 crab storage shares）");
+    return EXIT_USAGE;
+  }
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const res = await api2(credentials.apiBase, `/v1/storage/shares/${encodeURIComponent(shareId)}`, {
+    method: "DELETE",
+    headers: authHeaders(credentials)
+  });
+  if (res.status !== 200) {
+    console.error(errorMessage(res.body, "撤销失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  console.log(`✓ 已撤销分享（${shareId}）。`);
+  return 0;
+}
 async function storageQuota() {
   const credentials = requireCredentials();
   if (typeof credentials === "number")
@@ -7323,8 +7696,14 @@ switch (command) {
       process.exit(await storageMkCat(args.slice(2).join(" ") || undefined));
     if (sub === "tags")
       process.exit(await storageTags());
+    if (sub === "share")
+      process.exit(await storageShareCmd(args[2]));
+    if (sub === "shares")
+      process.exit(await storageShares(args[2]));
+    if (sub === "unshare")
+      process.exit(await storageUnshare(args[2]));
     console.error(sub ? `未知子命令：storage ${sub}
-` : `缺少子命令：storage ls | upload | download | rename | tag | category | publish | unpublish | rm | restore | purge | quota | categories | mkcat | tags
+` : `缺少子命令：storage ls | upload | download | rename | tag | category | publish | unpublish | rm | restore | purge | quota | categories | mkcat | tags | share | shares | unshare
 `);
     console.log(usage);
     process.exit(EXIT_USAGE);

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

@@ -12,7 +12,12 @@ description: Read, search and send the user's Crab Cloud platform email (usernam
 
 ## 第一步：确认可用
 
-- `crab --version` 确认已安装；未登录（退出码 3）引导用户 `crab login`。
+- 运行 `crab --version` 确认已安装。命令不存在时让用户运行
+  `npx @crabcloud/cli init`（登录 + 安装本 skill 一步完成）；已装过但命令缺失
+  时运行 `npx @crabcloud/cli@latest init` 升级。
+- CLI 基于 npx 分发，**本机没有 `crab` 命令时，下文所有 `crab <命令>` 都可以
+  `npx @crabcloud/cli <命令>` 等价执行**（例如 `npx @crabcloud/cli mail list`）。
+- 未登录（退出码 3）引导用户 `crab login`。
 - 邮箱动作需要对应 scope：读 `mail.read`、搜索 `mail.search`、发信 `mail.send`、
   删除 `mail.delete`。退出码 4 = scope 不足：如实转述缺哪个，引导用户
   `crab login --scopes mail`（组名 = 四项整组）或单列所需 scope 按需最小化
@@ -28,6 +33,8 @@ description: Read, search and send the user's Crab Cloud platform email (usernam
 | 读某封邮件 | `crab mail read <id>`（自动置已读；正文 + 操作记录） |
 | 找邮件 | `crab mail search <关键词>`（主题/发件人/收件人/正文，不含废纸篓） |
 | 发邮件 | `crab mail send --to a@x.cc --subject "..." --body "..."`（长正文用 `--body-file`） |
+| 发邮件带附件 | `crab mail send … --attach <云盘id\|文件名>[,…]`（引用云盘已有对象，不复制，≤10 个；先 `crab storage ls` 核对对象，文件名需精确唯一命中） |
+| 按名字/备注发邮件 | `--to`/`--cc` 可直接写联系人名（不含 `@`）：CLI 查联系人簿解析成地址，唯一命中即用；多候选会报错列出，改用完整地址重试。也可先 `crab contacts list <名字>`（`crabcloud` skill）查地址再发 |
 | 回信（带线程锚点） | 先 `crab mail read <id>` 取 Message-ID，再 `crab mail send --to … --in-reply-to <message-id> …` |
 | 整理邮箱 | `crab mail archive <id>` / `crab mail trash <id>` / `crab mail delete <id>` |
 
@@ -47,15 +54,21 @@ description: Read, search and send the user's Crab Cloud platform email (usernam
 
 - `mail list --json` → `{ items: [...], nextCursor }`，条目含
   `id/folder/fromAddr/to/subject/snippet/isUnread/hasAttachments/createdAt`；
-- `mail read --json` → 完整正文 + `actors`（谁读过/谁代发，审计源）；
+- `mail read --json` → 完整正文 + `attachments`（id/filename/mimeType/sizeBytes）
+  + `actors`（谁读过/谁代发，审计源）；
 - `mail send --json` → `{ message, chargedCredits, failedExternal }`。
 
 ## 纪律
 
 - **发邮件是外发动作**：发送前向用户复述收件人、主题与计费口径，确认后再执行；
-  不确定收件人身份时先搜索历史邮件核对，不要猜测地址。
+  不确定收件人身份时优先查联系人簿（`crab contacts list <名字>`，见 `crabcloud`
+  skill），其次搜索历史邮件核对，不要猜测地址。
 - **`mail delete` 是彻底删除**，不可恢复；用户没明说「彻底删除」时用
   `mail trash`（可找回，废纸篓 30 天后自动清除）。
 - 草稿流程：先 `mail list --folder drafts` 查看草稿；本阶段 CLI 不直接改草稿，
   确认发送请把草稿内容转述给用户后用 `mail send` 发出。
-- 附件：本阶段只标记 `hasAttachments`，附件内容尚未开放读取，如实说明。
+- 附件：`mail read` 输出附件清单（id/文件名/类型/体积）；附件内容归云盘管
+  ——下载用 `crab storage download <id>`（见 `crabcloud-storage` skill，跨来
+  源通用），发送引用云盘对象用 `mail send --attach`（对象须未被其他邮件绑
+  定；若报错说明已被引用，改走正文链接）。邮件详情附件显示「已在云盘删除」
+  表示对象已被软删，如实转述。

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

@@ -12,7 +12,12 @@ description: Manage the user's Crab Cloud Drive (云盘 — unified storage for
 
 ## 第一步：确认可用
 
-- `crab --version` 确认已安装；未登录（退出码 3）引导用户 `crab login`。
+- 运行 `crab --version` 确认已安装。命令不存在时让用户运行
+  `npx @crabcloud/cli init`（登录 + 安装本 skill 一步完成）；已装过但命令缺失
+  时运行 `npx @crabcloud/cli@latest init` 升级。
+- CLI 基于 npx 分发，**本机没有 `crab` 命令时，下文所有 `crab <命令>` 都可以
+  `npx @crabcloud/cli <命令>` 等价执行**（例如 `npx @crabcloud/cli storage ls`）。
+- 未登录（退出码 3）引导用户 `crab login`。
 - 动作需要对应 scope：列取/下载 `storage.read`，上传/改名/标签/分类/公开
   `storage.write`，移回收站/恢复/彻底删除 `storage.delete`。退出码 4 = scope
   不足：如实转述缺哪个，引导 `crab login --scopes storage`（组名 = 三项整组）
@@ -33,6 +38,7 @@ description: Manage the user's Crab Cloud Drive (云盘 — unified storage for
 | 加/删标签 | `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 publish <id\|文件名>`（打印公开直链；收回用 `unpublish`） |
+| 可控分享（有效期/提取码/撤销） | `crab storage share <id\|文件名> [--expires 7\|30\|90\|forever] [--passcode 提取码]`（打印完整分享链接；加密对象链接自带 `#` 密钥片段）；列表 `crab storage shares <id\|文件名>`、撤销 `crab storage unshare <shareId>` |
 | 删除 | `crab storage rm <id\|文件名>`（进回收站，7 天后自动清理）→ `restore` 恢复 / `purge` 彻底删除 |
 | 看水位 | `crab storage quota`（三来源分项 + 回收站占用 + 对象计数） |
 
@@ -44,7 +50,7 @@ restore/purge 直接用文件名即可）；命中多个或查不到时按字面
 
 程序化消费**始终加 `--json`**：
 
-- `storage ls --json` → `{ objects: [...], nextOffset }`，条目含
+- `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` 同构（单对象 / 分类数组 / 标签数组）。
@@ -53,6 +59,9 @@ restore/purge 直接用文件名即可）；命中多个或查不到时按字面
 
 - **publish 是对外公开**：公开后任何持链接者可访问，先向用户复述对象与后果，
   确认后再执行；收回用 `unpublish`（已缓存浏览器至多 5 分钟内失效）。
+- **share 是可控分享**：默认 7 天有效、可选提取码、随时 `unshare` 撤销；加密
+  对象的分享链接自带解密钥匙（`#` 后缀）——泄露链接即泄露文件，外发前向
+  用户复述有效期与提取码设置，确认后再执行。
 - **purge 是彻底删除**，不可恢复；用户没明说「彻底删除」时一律用 `rm`
   （回收站保留 7 天可找回）。
 - 邮件附件与用户上传同账：水位告急时用 `quota` 分项定位来源再建议清理。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crabcloud/cli",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "type": "module",
   "description": "Crab Cloud CLI (crab) — agent-first entry to your personal cloud, with skills bundled for Claude Code / Codex / ZCode.",
   "bin": {
@@ -24,6 +24,7 @@
     "prepublishOnly": "bun run typecheck && bun run build"
   },
   "devDependencies": {
+    "@crabcloud/cloudkit": "workspace:*",
     "@crabcloud/contracts": "workspace:*",
     "@crabcloud/skills": "workspace:*",
     "@types/bun": "latest",