@crabcloud/cli 0.1.7 → 0.1.9

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,12 +6,18 @@ 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 …`），协作尚未上线——用户问到时如实说明，
+**不要猜命令**。
 
 ## 第一步：确认可用
 
-- `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 按需最小化
@@ -27,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>` |
 
@@ -46,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

@@ -0,0 +1,69 @@
+---
+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` 确认已安装。命令不存在时让用户运行
+  `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`（组名 = 三项整组）
+  重新授权（你只发起，不代批）。
+- 退出码 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 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`（三来源分项 + 回收站占用 + 对象计数） |
+
+`<id|文件名>`：文件名全库精确唯一命中时自动解析为 id（回收站内同样可解析，
+restore/purge 直接用文件名即可）；命中多个或查不到时按字面当 id 用——拿不准
+先 `crab storage ls --q <关键字>` 核对再操作。
+
+## 机器可读输出
+
+程序化消费**始终加 `--json`**：
+
+- `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` 同构（单对象 / 分类数组 / 标签数组）。
+
+## 纪律
+
+- **publish 是对外公开**：公开后任何持链接者可访问，先向用户复述对象与后果，
+  确认后再执行；收回用 `unpublish`（已缓存浏览器至多 5 分钟内失效）。
+- **share 是可控分享**：默认 7 天有效、可选提取码、随时 `unshare` 撤销；加密
+  对象的分享链接自带解密钥匙（`#` 后缀）——泄露链接即泄露文件，外发前向
+  用户复述有效期与提取码设置，确认后再执行。
+- **purge 是彻底删除**，不可恢复；用户没明说「彻底删除」时一律用 `rm`
+  （回收站保留 7 天可找回）。
+- 邮件附件与用户上传同账：水位告急时用 `quota` 分项定位来源再建议清理。
+- 公开直链的呈现方式由服务端策略决定（图片/视频/音频/PDF/纯文本内联，SVG 与
+  其他类型强制下载），CLI 侧没有、也不需要有开关。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crabcloud/cli",
-  "version": "0.1.7",
+  "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",