@crabcloud/cli 0.1.7 → 0.1.8

package/dist/crab.js

@@ -3,7 +3,7 @@
 // src/index.ts
 import { hostname, homedir as homedir2 } from "node:os";
 import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join2 } from "node:path";
+import { basename, join as join2 } from "node:path";
 
 // ../../node_modules/.bun/zod@4.6.5/node_modules/zod/v4/core/util.js
 function getEnumValues(entries) {
@@ -5724,6 +5724,9 @@ function superRefine(fn, params) {
 var accountDomain = "crabcloud.cc";
 var adminDomain = `admin.${accountDomain}`;
 var storageDomain = `storage.${accountDomain}`;
+function storagePublicUrl(objectId) {
+  return `https://${storageDomain}/o/${objectId}`;
+}
 var clientTypes = ["web", "agent", "miniapp", "native"];
 var scopes = [
   "account.read",
@@ -5791,7 +5794,7 @@ var registerInput = object({
   code: string2().trim().regex(/^\d{6}$/),
   displayName: string2().trim().min(1).max(80),
   password: string2().min(8).max(256),
-  invite: string2().trim().min(16).max(128).optional()
+  invite: string2().trim().max(64).transform((v) => v.toUpperCase()).optional()
 });
 var loginInput = object({
   username: string2().trim().toLowerCase().min(3).max(254),
@@ -6209,6 +6212,7 @@ function exitCodeForApiError(body) {
     case "bad_request":
       return EXIT_USAGE;
     case "insufficient_credits":
+    case "storage.quotaExceeded":
       return EXIT_QUOTA;
     default:
       return 1;
@@ -6268,6 +6272,33 @@ var usage = `crab — Crab Cloud CLI（Agent-first 入口）
        [--in-reply-to <message-id>]      回信线程锚点（原信 RFC Message-ID，crab mail read 可见）
                        发送邮件：平台内（@crabcloud.cc）免费，外部出站 2 积分/封
   mail archive|trash|delete <id>     移夹 / 废纸篓 / 彻底删除（delete 不可恢复）
+  contacts list [query] [--offset N] [--json]     列出联系人（地址前缀/显示名匹配）
+  contacts add <address> [--name 名] [--note 备注] [--json]
+                                     添加联系人（站内地址自动关联对方账号）
+  contacts rm <id|address>           删除联系人
+  contacts invite [--reset] [--json] 我的邀请码、链接与统计（--reset 重置，旧链接失效）
+  contacts invitees [--offset N] [--json]
+                                     我邀请的人（直接下级 + 间接计数）
+  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]
+                                     列出云盘对象（跨来源统一视图，能力与 Web 云盘一致）
+  storage upload <file...> [--json]  上传一个或多个文件（直传优先，自动回退中转）
+  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 publish|unpublish <id|文件名>
+                                     公开 / 收回公开（公开时打印公开直链）
+  storage rm|restore|purge <id|文件名>
+                                     回收站 / 恢复 / 彻底删除（purge 不可恢复）
+  storage quota [--json]             存储水位（统一容量账：文件/素材/邮件附件一本账）
+  storage categories [--json]        分类列表
+  storage mkcat <名称>               新建分类
+  storage tags [--json]              标签汇总
   skills install|list|uninstall [--agent claude,zcode,codex,agents]
                        skills 管理（claude/zcode/agents 复制目录，codex 写 AGENTS.md 段）
   logout               撤销当前 Agent Token 并清除本地凭证
@@ -6594,6 +6625,582 @@ async function mailMove(action, id) {
   console.log(`✓ ${action === "archive" ? "已归档" : action === "trash" ? "已移入废纸篓" : "已彻底删除"}（${id}）`);
   return 0;
 }
+function contactDisplayName(contact) {
+  return contact.displayName ?? contact.resolvedName ?? contact.address;
+}
+async function contactsList(query) {
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const params = new URLSearchParams;
+  if (query)
+    params.set("query", query);
+  const offset = readFlag("--offset");
+  if (offset)
+    params.set("offset", offset);
+  params.set("limit", readFlag("--limit") ?? "30");
+  const res = await api2(credentials.apiBase, `/v1/contacts?${params}`, { headers: authHeaders(credentials) });
+  if (res.status !== 200) {
+    console.error(errorMessage(res.body, "获取联系人失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  const page = res.body.data;
+  if (hasFlag("--json")) {
+    console.log(JSON.stringify(page, null, 2));
+    return 0;
+  }
+  if (page.items.length === 0) {
+    console.log("还没有联系人。");
+    return 0;
+  }
+  for (const contact of page.items) {
+    const name = contactDisplayName(contact);
+    const address = name === contact.address ? "" : ` <${contact.address}>`;
+    const linked = contact.linkedUsername ? `  [站内 ${contact.linkedUsername}]` : "";
+    console.log(`${contact.id}  ${name}${address}${linked}`);
+  }
+  console.log(`共 ${page.total} 条`);
+  if (page.nextOffset !== null)
+    console.log(`（还有更多：contacts list --offset ${page.nextOffset}）`);
+  return 0;
+}
+async function contactsAdd(address) {
+  if (!address) {
+    console.error("用法：crab contacts add <address> [--name 显示名] [--note 备注] [--json]");
+    return EXIT_USAGE;
+  }
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const body = { address };
+  const name = readFlag("--name");
+  if (name)
+    body.displayName = name;
+  const note = readFlag("--note");
+  if (note)
+    body.note = note;
+  const res = await api2(credentials.apiBase, "/v1/contacts", {
+    method: "POST",
+    headers: authHeaders(credentials),
+    body: JSON.stringify(body)
+  });
+  if (res.status !== 200 && res.status !== 201) {
+    console.error(errorMessage(res.body, "添加失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  const contact = res.body.data;
+  if (hasFlag("--json")) {
+    console.log(JSON.stringify(contact, null, 2));
+    return 0;
+  }
+  console.log(`✓ 已添加：${contactDisplayName(contact)} <${contact.address}>（id ${contact.id}）`);
+  return 0;
+}
+async function contactsRm(idOrAddress) {
+  if (!idOrAddress) {
+    console.error("用法：crab contacts rm <id|address>");
+    return EXIT_USAGE;
+  }
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  let id = idOrAddress;
+  if (idOrAddress.includes("@")) {
+    const res = await api2(credentials.apiBase, `/v1/contacts?query=${encodeURIComponent(idOrAddress)}&limit=50`, {
+      headers: authHeaders(credentials)
+    });
+    if (res.status !== 200) {
+      console.error(errorMessage(res.body, "查找联系人失败。"));
+      return exitCodeForApiError(res.body);
+    }
+    const page = res.body.data;
+    const hit = page.items.find((item) => item.address === idOrAddress.toLowerCase());
+    if (!hit) {
+      console.error("联系人不存在或已删除。");
+      return EXIT_NOT_FOUND;
+    }
+    id = hit.id;
+  }
+  const res = await api2(credentials.apiBase, `/v1/contacts/${encodeURIComponent(id)}`, {
+    method: "DELETE",
+    headers: authHeaders(credentials)
+  });
+  if (res.status !== 200) {
+    console.error(errorMessage(res.body, "删除失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  console.log(`✓ 已删除（${id}）`);
+  return 0;
+}
+async function contactsInvite(reset) {
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const res = await api2(credentials.apiBase, "/v1/contacts/invite/reset", {
+    method: reset ? "POST" : "GET",
+    headers: authHeaders(credentials)
+  });
+  if (res.status !== 200) {
+    console.error(errorMessage(res.body, "获取邀请链接失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  const overview = res.body.data;
+  if (hasFlag("--json")) {
+    console.log(JSON.stringify(overview, null, 2));
+    return 0;
+  }
+  console.log(`邀请码：${overview.token}`);
+  console.log(`邀请链接：https://crabcloud.cc/register?invite=${overview.token}`);
+  console.log(`已邀请 ${overview.directCount} 人 · 含间接 ${overview.indirectCount} 人`);
+  if (!reset)
+    console.log("（重置链接：crab contacts invite --reset）");
+  return 0;
+}
+async function contactsInvitees() {
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const offset = readFlag("--offset");
+  const res = await api2(credentials.apiBase, `/v1/contacts/invitees?offset=${offset ?? "0"}&limit=30`, {
+    headers: authHeaders(credentials)
+  });
+  if (res.status !== 200) {
+    console.error(errorMessage(res.body, "获取邀请列表失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  const page = res.body.data;
+  if (hasFlag("--json")) {
+    console.log(JSON.stringify(page, null, 2));
+    return 0;
+  }
+  if (page.items.length === 0) {
+    console.log("还没有人通过你的链接加入。");
+    return 0;
+  }
+  for (const invitee of page.items) {
+    console.log(`${invitee.username}  ${invitee.displayName}  ${new Date(invitee.joinedAt).toLocaleDateString("zh-CN")}`);
+  }
+  console.log(`直接 ${page.directTotal} · 间接 ${page.indirectTotal}`);
+  if (page.nextOffset !== null)
+    console.log(`（还有更多：contacts invitees --offset ${page.nextOffset}）`);
+  return 0;
+}
+var STORAGE_SOURCES = ["files", "media", "mail"];
+var STORAGE_TYPES = ["doc", "image", "video", "archive", "code"];
+var MIME_BY_EXT = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  pdf: "application/pdf",
+  txt: "text/plain",
+  md: "text/markdown",
+  csv: "text/csv",
+  json: "application/json",
+  xml: "application/xml",
+  yaml: "application/x-yaml",
+  yml: "application/x-yaml",
+  js: "text/javascript",
+  zip: "application/zip",
+  gz: "application/gzip",
+  mp3: "audio/mpeg",
+  mp4: "video/mp4"
+};
+function mimeFor(filename) {
+  const ext = filename.split(".").pop()?.toLowerCase() ?? "";
+  return MIME_BY_EXT[ext] ?? "application/octet-stream";
+}
+function formatBytesCli(n) {
+  if (n >= 1073741824)
+    return `${(n / 1073741824).toFixed(1)} GB`;
+  if (n >= 1048576)
+    return `${(n / 1048576).toFixed(1)} MB`;
+  if (n >= 1024)
+    return `${(n / 1024).toFixed(1)} KB`;
+  return `${n} B`;
+}
+function printStorageRow(o) {
+  const flags = [
+    o.source !== "files" ? o.source === "media" ? "素材" : "邮件附件" : 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) {
+  for (const trash of [false, true]) {
+    const params = new URLSearchParams({ limit: "100", q: token });
+    if (trash)
+      params.set("trash", "1");
+    const res = await api2(credentials.apiBase, `/v1/storage?${params}`, {
+      headers: authHeaders(credentials)
+    });
+    if (res.status !== 200) {
+      console.error(errorMessage(res.body, "查找对象失败。"));
+      return exitCodeForApiError(res.body);
+    }
+    const exact = res.body.data.objects.filter((o) => o.filename === token);
+    if (exact.length > 1) {
+      console.error(`文件名「${token}」命中多个对象，请用 id 指定（crab storage ls 查询）。`);
+      return EXIT_USAGE;
+    }
+    if (exact.length === 1)
+      return exact[0].id;
+  }
+  return token;
+}
+async function storageList() {
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const params = new URLSearchParams({ limit: readFlag("--limit") ?? "30" });
+  const source = readFlag("--source");
+  if (source) {
+    if (!STORAGE_SOURCES.includes(source)) {
+      console.error(`未知来源：${source}
+可用：${STORAGE_SOURCES.join(", ")}`);
+      return EXIT_USAGE;
+    }
+    params.set("source", source);
+  }
+  const type = readFlag("--type");
+  if (type) {
+    if (!STORAGE_TYPES.includes(type)) {
+      console.error(`未知类型：${type}
+可用：${STORAGE_TYPES.join(", ")}`);
+      return EXIT_USAGE;
+    }
+    params.set("type", type);
+  }
+  const category = readFlag("--category");
+  if (category)
+    params.set("category", category);
+  const tags = readFlag("--tag");
+  if (tags)
+    params.set("tags", tags);
+  if (hasFlag("--trash"))
+    params.set("trash", "1");
+  if (hasFlag("--shared"))
+    params.set("public", "1");
+  if (hasFlag("--recent"))
+    params.set("since", String(Date.now() - 604800000));
+  const offset = readFlag("--offset");
+  if (offset)
+    params.set("offset", offset);
+  const q = readFlag("--q");
+  if (q)
+    params.set("q", q);
+  const res = await api2(credentials.apiBase, `/v1/storage?${params}`, { headers: authHeaders(credentials) });
+  if (res.status !== 200) {
+    console.error(errorMessage(res.body, "获取云盘列表失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  const page = res.body.data;
+  if (hasFlag("--json")) {
+    console.log(JSON.stringify(page, null, 2));
+    return 0;
+  }
+  if (page.objects.length === 0) {
+    console.log("云盘里没有匹配的对象。");
+    return 0;
+  }
+  for (const object of page.objects)
+    printStorageRow(object);
+  if (page.nextOffset !== null)
+    console.log(`（还有更多：storage ls --offset ${page.nextOffset}）`);
+  return 0;
+}
+async function storageUploadOne(credentials, filePath) {
+  let buf;
+  try {
+    buf = readFileSync2(filePath);
+  } catch {
+    console.error(`读取文件失败：${filePath}`);
+    return EXIT_USAGE;
+  }
+  const filename = basename(filePath);
+  const mimeType = mimeFor(filename);
+  const presign = await api2(credentials.apiBase, "/v1/storage/presign", {
+    method: "POST",
+    headers: authHeaders(credentials),
+    body: JSON.stringify({ filename, mimeType, sizeBytes: buf.byteLength })
+  });
+  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 } });
+    if (!put.ok) {
+      console.error(`直传失败（${put.status}）：${filename}`);
+      return 1;
+    }
+    const complete = await api2(credentials.apiBase, `/v1/storage/${encodeURIComponent(fileId)}/complete`, {
+      method: "POST",
+      headers: authHeaders(credentials),
+      body: "{}"
+    });
+    if (complete.status !== 200 && complete.status !== 201) {
+      console.error(errorMessage(complete.body, `记账失败：${filename}`));
+      return exitCodeForApiError(complete.body);
+    }
+    const object = complete.body.data;
+    if (hasFlag("--json"))
+      console.log(JSON.stringify(object, null, 2));
+    else
+      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);
+    const res = await fetch(`${credentials.apiBase}/v1/storage`, {
+      method: "POST",
+      headers: authHeaders(credentials),
+      body: form
+    });
+    const body = await res.json().catch(() => ({}));
+    if (res.status !== 200 && res.status !== 201) {
+      console.error(body.error?.message ?? `上传失败：${filename}`);
+      return exitCodeForApiError(body);
+    }
+    if (hasFlag("--json"))
+      console.log(JSON.stringify(body.data, null, 2));
+    else
+      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("--"));
+  if (files.length === 0) {
+    console.error("用法：crab storage upload <file...> [--json]");
+    return EXIT_USAGE;
+  }
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  let code = 0;
+  for (const file of files) {
+    const result = await storageUploadOne(credentials, file);
+    if (result !== 0 && code === 0)
+      code = result;
+    if (result === EXIT_AUTH || result === EXIT_SCOPE)
+      return result;
+  }
+  return code;
+}
+async function storageDownload(token) {
+  if (!token) {
+    console.error("用法：crab storage download <id|文件名> [-o 输出路径]");
+    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 fetch(`${credentials.apiBase}/v1/storage/${encodeURIComponent(id)}/content`, {
+    headers: authHeaders(credentials)
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    console.error(errorMessage(body, "下载失败。"));
+    return exitCodeForApiError(body);
+  }
+  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))}）`);
+  return 0;
+}
+async function storagePatch(credentials, token, patch) {
+  const id = await resolveStorageId(credentials, token);
+  if (typeof id === "number")
+    return id;
+  const res = await api2(credentials.apiBase, `/v1/storage/${encodeURIComponent(id)}`, {
+    method: "PATCH",
+    headers: authHeaders(credentials),
+    body: JSON.stringify(patch)
+  });
+  if (res.status !== 200) {
+    console.error(errorMessage(res.body, "更新失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  return res.body.data;
+}
+async function storageRename(token, name) {
+  if (!token || !name) {
+    console.error("用法：crab storage rename <id|文件名> <新名称>");
+    return EXIT_USAGE;
+  }
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const result = await storagePatch(credentials, token, { filename: name });
+  if (typeof result === "number")
+    return result;
+  console.log(`✓ 已重命名：${result.filename}（id ${result.id}）`);
+  return 0;
+}
+async function storageTag(token) {
+  if (!token || !hasFlag("--add") && !hasFlag("--remove")) {
+    console.error("用法：crab storage tag <id|文件名> --add a,b [--remove c,d]");
+    return EXIT_USAGE;
+  }
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const add = (readFlag("--add") ?? "").split(",").map((t) => t.trim()).filter(Boolean);
+  const remove = (readFlag("--remove") ?? "").split(",").map((t) => t.trim()).filter(Boolean);
+  const patch = {};
+  if (add.length > 0)
+    patch.addTags = add;
+  if (remove.length > 0)
+    patch.removeTags = remove;
+  const result = await storagePatch(credentials, token, patch);
+  if (typeof result === "number")
+    return result;
+  console.log(`✓ 标签已更新：${result.filename} [${result.tags.join(", ") || "无"}]`);
+  return 0;
+}
+async function storageCategory(token, value) {
+  if (!token || !value) {
+    console.error("用法：crab storage category <id|文件名> <categoryId|none>（分类 id 见 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 });
+  if (typeof result === "number")
+    return result;
+  console.log(`✓ 分类已更新：${result.filename}`);
+  return 0;
+}
+async function storagePublish(token, publish) {
+  if (!token) {
+    console.error(`用法：crab storage ${publish ? "publish" : "unpublish"} <id|文件名>`);
+    return EXIT_USAGE;
+  }
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const result = await storagePatch(credentials, token, { isPublic: publish });
+  if (typeof result === "number")
+    return result;
+  console.log(`✓ ${publish ? "已公开" : "已收回公开"}：${result.filename}`);
+  if (publish)
+    console.log(`  公开链接：${storagePublicUrl(result.id)}`);
+  return 0;
+}
+async function storageMove(action, token) {
+  if (!token) {
+    console.error(`用法：crab storage ${action} <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)}${action === "restore" ? "/restore" : ""}${action === "purge" ? "/purge" : ""}`, { method: action === "restore" ? "POST" : "DELETE", headers: authHeaders(credentials) });
+  if (res.status !== 200) {
+    console.error(errorMessage(res.body, "操作失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  console.log(`✓ ${action === "rm" ? "已移入回收站（7 天后自动清理）" : action === "restore" ? "已恢复" : "已彻底删除"}（${id}）`);
+  return 0;
+}
+async function storageQuota() {
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const res = await api2(credentials.apiBase, "/v1/storage/quota", { headers: authHeaders(credentials) });
+  if (res.status !== 200) {
+    console.error(errorMessage(res.body, "获取水位失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  const quota = res.body.data;
+  if (hasFlag("--json")) {
+    console.log(JSON.stringify(quota, null, 2));
+    return 0;
+  }
+  const pct = quota.quotaBytes > 0 ? (quota.usedBytes / quota.quotaBytes * 100).toFixed(1) : "0";
+  console.log(`已用 ${formatBytesCli(quota.usedBytes)} / ${formatBytesCli(quota.quotaBytes)}（${pct}%）`);
+  console.log(`  文件 ${formatBytesCli(quota.bySource.files)} · 素材 ${formatBytesCli(quota.bySource.media)} · 邮件附件 ${formatBytesCli(quota.bySource.mail)} · 回收站 ${formatBytesCli(quota.trashBytes)}`);
+  console.log(`  对象数：全部 ${quota.counts.all ?? 0} · 素材 ${quota.counts.media ?? 0} · 邮件附件 ${quota.counts.mail ?? 0} · 共享 ${quota.counts.shared ?? 0} · 回收站 ${quota.counts.trash ?? 0}`);
+  return 0;
+}
+async function storageCategories() {
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  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;
+  if (hasFlag("--json")) {
+    console.log(JSON.stringify(rows, null, 2));
+    return 0;
+  }
+  if (rows.length === 0) {
+    console.log("还没有分类（crab storage mkcat <名称> 创建）。");
+    return 0;
+  }
+  for (const row of rows)
+    console.log(`${row.id}  ${row.name}  (${row.fileCount})`);
+  return 0;
+}
+async function storageMkCat(name) {
+  if (!name) {
+    console.error("用法：crab storage mkcat <名称>");
+    return EXIT_USAGE;
+  }
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const res = await api2(credentials.apiBase, "/v1/storage/categories", {
+    method: "POST",
+    headers: authHeaders(credentials),
+    body: JSON.stringify({ name })
+  });
+  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}）`);
+  return 0;
+}
+async function storageTags() {
+  const credentials = requireCredentials();
+  if (typeof credentials === "number")
+    return credentials;
+  const res = await api2(credentials.apiBase, "/v1/storage/tags", { headers: authHeaders(credentials) });
+  if (res.status !== 200) {
+    console.error(errorMessage(res.body, "获取标签失败。"));
+    return exitCodeForApiError(res.body);
+  }
+  const rows = res.body.data;
+  if (hasFlag("--json")) {
+    console.log(JSON.stringify(rows, null, 2));
+    return 0;
+  }
+  if (rows.tags.length === 0) {
+    console.log("还没有标签（crab storage tag <id> --add a,b 添加）。");
+    return 0;
+  }
+  for (const row of rows.tags)
+    console.log(`${row.tag}  (${row.count})`);
+  return 0;
+}
 async function init() {
   if (loadCredentials()) {
     console.log("已登录（crab whoami 查看身份）。");
@@ -6666,6 +7273,58 @@ switch (command) {
       process.exit(await mailMove(sub, args[2]));
     console.error(sub ? `未知子命令：mail ${sub}
 ` : `缺少子命令：mail list | read | search | send | archive | trash | delete
+`);
+    console.log(usage);
+    process.exit(EXIT_USAGE);
+  }
+  case "contacts": {
+    const sub = args[1];
+    if (sub === "list")
+      process.exit(await contactsList(args.slice(2).join(" ") || undefined));
+    if (sub === "add")
+      process.exit(await contactsAdd(args[2]));
+    if (sub === "rm")
+      process.exit(await contactsRm(args[2]));
+    if (sub === "invite")
+      process.exit(await contactsInvite(hasFlag("--reset")));
+    if (sub === "invitees")
+      process.exit(await contactsInvitees());
+    console.error(sub ? `未知子命令：contacts ${sub}
+` : `缺少子命令：contacts list | add | rm | invite | invitees
+`);
+    console.log(usage);
+    process.exit(EXIT_USAGE);
+  }
+  case "storage": {
+    const sub = args[1];
+    if (sub === "ls")
+      process.exit(await storageList());
+    if (sub === "upload")
+      process.exit(await storageUpload(args.slice(2)));
+    if (sub === "download")
+      process.exit(await storageDownload(args[2]));
+    if (sub === "rename")
+      process.exit(await storageRename(args[2], args[3]));
+    if (sub === "tag")
+      process.exit(await storageTag(args[2]));
+    if (sub === "category")
+      process.exit(await storageCategory(args[2], args[3]));
+    if (sub === "publish")
+      process.exit(await storagePublish(args[2], true));
+    if (sub === "unpublish")
+      process.exit(await storagePublish(args[2], false));
+    if (sub === "rm" || sub === "restore" || sub === "purge")
+      process.exit(await storageMove(sub, args[2]));
+    if (sub === "quota")
+      process.exit(await storageQuota());
+    if (sub === "categories")
+      process.exit(await storageCategories());
+    if (sub === "mkcat")
+      process.exit(await storageMkCat(args.slice(2).join(" ") || undefined));
+    if (sub === "tags")
+      process.exit(await storageTags());
+    console.error(sub ? `未知子命令：storage ${sub}
+` : `缺少子命令：storage ls | upload | download | rename | tag | category | publish | unpublish | rm | restore | purge | quota | categories | mkcat | tags
 `);
     console.log(usage);
     process.exit(EXIT_USAGE);

package/dist/skills/crabcloud/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: crabcloud
-description: Manage the user's Crab Cloud personal cloud account and agent tokens through the `crab` CLI — check identity/subscription/credits, list and revoke authorized agent tokens, and re-authorize with specific scopes or scope groups. Use this skill whenever the user asks about their Crab Cloud account ("我的账号信息", "who am I on crabcloud"), wants to see or clean up authorized agents/tokens ("看看我授权了哪些 agent", "revoke that old token", "撤销那个旧令牌"), or asks how to connect their coding agent to Crab Cloud — even if they never say "crab" or "Crab Cloud" explicitly. Email lives in the crabcloud-mail skill (crab mail …); the Drive web app is live but has no CLI commands yet; collab and contacts ship in later phases.
+description: Manage the user's Crab Cloud personal cloud account and agent tokens through the `crab` CLI — check identity/subscription/credits, list and revoke authorized agent tokens, and re-authorize with specific scopes or scope groups. Use this skill whenever the user asks about their Crab Cloud account ("我的账号信息", "who am I on crabcloud"), wants to see or clean up authorized agents/tokens ("看看我授权了哪些 agent", "revoke that old token", "撤销那个旧令牌"), manages their contacts ("我的联系人", "把 zhangsan 加到联系人", "我的邀请码"), or asks how to connect their coding agent to Crab Cloud — even if they never say "crab" or "Crab Cloud" explicitly. Contacts are managed with `crab contacts …` in this skill; email lives in the crabcloud-mail skill (crab mail …) and the Drive in crabcloud-storage (crab storage …); collab ships in a later phase.
 ---
 
 # Crab Cloud（平台 / 账号域）
@@ -8,9 +8,10 @@ description: Manage the user's Crab Cloud personal cloud account and agent token
 Crab Cloud 是用户的个人云底座：账号、订阅与积分是平台层，邮箱 / 云盘 / 协作 /
 联系人是独立应用。`crab` CLI 是 Agent 的稳定接口：凭证在用户本机
 （`~/.config/crabcloud/credentials.json`，0600），服务端只存令牌哈希、全程审计。
-本 skill 覆盖**平台与账号域**；邮箱已上线，见 `crabcloud-mail` skill（`crab mail …`）；
-云盘已在网页上线但 **agent 通道（CLI 命令）尚未开放**，协作、联系人随后续阶段
-提供——用户问到这些时如实说明，**不要猜命令**。
+本 skill 覆盖**平台、账号域与联系人**（`crab contacts …`）；邮箱见
+`crabcloud-mail` skill（`crab mail …`），
+云盘见 `crabcloud-storage` skill（`crab storage …`）；协作随后续阶段
+提供——用户问到时如实说明，**不要猜命令**。
 
 ## 第一步：确认 CLI 可用
 
@@ -33,6 +34,9 @@ Crab Cloud 是用户的个人云底座：账号、订阅与积分是平台层，
 | 撤销某个令牌（高危，先确认） | `crab tokens revoke <id>` |
 | 重新授权 / 调整 scope | `crab login --scopes mail`（组名整组授权；也可单 scope 如 `mail.read`。浏览器确认，你只发起） |
 | 登出并吊销当前令牌 | `crab logout` |
+| 联系人：列出 / 搜索 | `crab contacts list [query]`（`--offset`/`--limit` 分页，输出含「共 N 条」） |
+| 联系人：添加 / 删除 | `crab contacts add <address> [--name 名] [--note 备注]` / `crab contacts rm <id|address>` |
+| 我的邀请码、邀请链接与受邀名单 | `crab contacts invite [--reset]` / `crab contacts invitees` |
 | 管理登录设备 / 会话、修改密码 | 网页个人中心（crabcloud.cc/account）——CLI 有意不开放 |
 
 拿不准令牌 id 时先 `crab tokens list` 核对；`revoke` 只接受列表里的 id。
@@ -64,9 +68,11 @@ Crab Cloud 是用户的个人云底座：账号、订阅与积分是平台层，
   不要怂恿用户一次性给全量 scope。`--scopes` 支持组名（`mail` = 读写搜删四项
   整组）与单个 scope 混用；组目录见 `crab help`，可用组：account / mail /
   storage（云盘，含素材与附件）/ collab / contacts。
-- 如实转述能力边界：云盘已在网页上线但 agent 通道尚未开放（没有
-  `crab storage` 等命令），协作、联系人尚未上线——相关请求如实说明，引导用户
-  用网页（crabcloud.cc），不要编造命令或输出；邮箱请求转交 `crabcloud-mail` skill。
+- 如实转述能力边界：协作尚未上线——相关请求如实说明，引导用户
+  用网页（crabcloud.cc），不要编造命令或输出；联系人已上线，用 `crab contacts`
+  （list / add / rm / invite / invitees；scope contacts.read/write，程序消费加
+  `--json`）处理；邮箱请求转交 `crabcloud-mail`
+  skill，云盘请求转交 `crabcloud-storage` skill。
 - 账号安全操作（修改密码、登录设备/会话的查看与吊销）**有意不开放给 agent
   通道**：改密对令牌持有者是账号接管面，会话属于"人的浏览器会话"。用户让
   agent 做这些时，如实说明并引导到网页个人中心（crabcloud.cc/account）操作，

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

@@ -6,8 +6,9 @@ description: Read, search and send the user's Crab Cloud platform email (usernam
 # Crab Cloud 邮箱（crab mail）
 
 用户的 Crab Cloud 账号自带平台邮箱 `username@crabcloud.cc`（用户名即地址本地部分）。
-本 skill 覆盖邮箱域的 agent 通道；账号/令牌管理见 `crabcloud` skill。云盘已在网页
-上线（agent 通道未开放），协作尚未上线——用户问到时如实说明，**不要猜命令**。
+本 skill 覆盖邮箱域的 agent 通道；账号/令牌管理见 `crabcloud` skill。云盘见
+`crabcloud-storage` skill（`crab storage …`），协作尚未上线——用户问到时如实说明，
+**不要猜命令**。
 
 ## 第一步：确认可用
 

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

@@ -0,0 +1,60 @@
+---
+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.
+---
+
+# Crab Cloud 云盘（crab storage）
+
+云盘是用户的统一存储：云盘上传 / 素材库 / 邮件附件三来源共用一本 2 GB 容量账；
+属性优先、位置无关——分类（至多一个）+ 标签（AND 检索）代替文件夹。本 skill
+覆盖云盘域的 agent 通道；账号/令牌管理见 `crabcloud` skill，邮箱见
+`crabcloud-mail` skill。
+
+## 第一步：确认可用
+
+- `crab --version` 确认已安装；未登录（退出码 3）引导用户 `crab login`。
+- 动作需要对应 scope：列取/下载 `storage.read`，上传/改名/标签/分类/公开
+  `storage.write`，移回收站/恢复/彻底删除 `storage.delete`。退出码 4 = scope
+  不足：如实转述缺哪个，引导 `crab login --scopes storage`（组名 = 三项整组）
+  重新授权（你只发起，不代批）。
+- 退出码 7 = `storage.quotaExceeded`（统一容量账满，2 GB）：告知用户，可建议
+  清理回收站或大文件（`storage quota` 看分项），不要自动重试。
+
+## 意图 → 命令映射
+
+| 用户意图 | 命令 |
+|---|---|
+| 云盘里有什么 | `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 --trash` |
+| 上传文件 | `crab storage upload <路径...>`（多文件串行；直传优先，自动回退中转） |
+| 下载文件 | `crab storage download <id\|文件名> [-o 输出路径]`（默认按原文件名存当前目录） |
+| 改名 | `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 publish <id\|文件名>`（打印公开直链；收回用 `unpublish`） |
+| 删除 | `crab storage rm <id\|文件名>`（进回收站，7 天后自动清理）→ `restore` 恢复 / `purge` 彻底删除 |
+| 看水位 | `crab storage quota`（三来源分项 + 回收站占用 + 对象计数） |
+
+`<id|文件名>`：文件名全库精确唯一命中时自动解析为 id（回收站内同样可解析，
+restore/purge 直接用文件名即可）；命中多个或查不到时按字面当 id 用——拿不准
+先 `crab storage ls --q <关键字>` 核对再操作。
+
+## 机器可读输出
+
+程序化消费**始终加 `--json`**：
+
+- `storage ls --json` → `{ objects: [...], nextOffset }`，条目含
+  `id / source / filename / mimeType / sizeBytes / categoryId / tags / isPublic / createdAt`；
+- `storage quota --json` → `{ usedBytes, quotaBytes, bySource: { files, media, mail }, trashBytes, counts }`；
+- `upload` / `categories` / `tags` 的 `--json` 同构（单对象 / 分类数组 / 标签数组）。
+
+## 纪律
+
+- **publish 是对外公开**：公开后任何持链接者可访问，先向用户复述对象与后果，
+  确认后再执行；收回用 `unpublish`（已缓存浏览器至多 5 分钟内失效）。
+- **purge 是彻底删除**，不可恢复；用户没明说「彻底删除」时一律用 `rm`
+  （回收站保留 7 天可找回）。
+- 邮件附件与用户上传同账：水位告急时用 `quota` 分项定位来源再建议清理。
+- 公开直链的呈现方式由服务端策略决定（图片/视频/音频/PDF/纯文本内联，SVG 与
+  其他类型强制下载），CLI 侧没有、也不需要有开关。

package/package.json

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