@crabcloud/skills 0.1.0 → 0.1.2

package/dist/skills/crabcloud/SKILL.md

@@ -1,15 +1,17 @@
 ---
 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. 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. Mail, files and projects capabilities ship with their own skills (crabcloud-mail etc.) 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（平台 / 账号域）
 
-Crab Cloud 是用户的个人云底座：账号、订阅与积分是平台层，邮箱 / 云文件 / 协作项目
-是独立应用。`crab` CLI 是 Agent 的稳定接口：凭证在用户本机
+Crab Cloud 是用户的个人云底座：账号、订阅与积分是平台层，邮箱 / 云盘 / 协作 /
+联系人是独立应用。`crab` CLI 是 Agent 的稳定接口：凭证在用户本机
 （`~/.config/crabcloud/credentials.json`，0600），服务端只存令牌哈希、全程审计。
-本 skill 目前覆盖**平台与账号域**；邮箱（`crabcloud-mail`）、云文件、协作项目
-能力随各阶段上线——用户问到这些时如实说明尚未开放，**不要猜命令**。
+本 skill 覆盖**平台、账号域与联系人**（`crab contacts …`）；邮箱见
+`crabcloud-mail` skill（`crab mail …`），
+云盘见 `crabcloud-storage` skill（`crab storage …`）；协作随后续阶段
+提供——用户问到时如实说明，**不要猜命令**。
 
 ## 第一步：确认 CLI 可用
 
@@ -17,7 +19,9 @@ Crab Cloud 是用户的个人云底座：账号、订阅与积分是平台层，
   `npx @crabcloud/cli init`（登录 + 安装本 skill 一步完成）；已装过但命令缺失
   时运行 `npx @crabcloud/cli@latest init` 升级。
 - `crab whoami` 报「未登录」或退出码 3 → 引导用户 `crab login`。登录走浏览器
-  设备授权（用户逐条确认 scope）——**你只发起，不代批**。
+  设备授权——授权页摆出全目录供用户勾选，**实际授予集由人定**，可能多于或少于
+  `--scopes` 请求——**你只发起，不代批**；登录后先 `crab whoami` 核对实际
+  scopes 再干活，缺什么就引导用户带组名/scope 重新授权。
 - 永远不要让用户把 token 粘贴进对话；凭证文件与你无关，也不要读取它。
 
 ## 意图 → 命令映射
@@ -26,18 +30,29 @@ Crab Cloud 是用户的个人云底座：账号、订阅与积分是平台层，
 |---|---|
 | 看账号身份 / 订阅 / 积分 | `crab whoami` |
 | 程序化读取身份 | `crab whoami --json` |
+| 积分余额（月送/充值/合计） | `crab credits`（需 `credits.read`，脚本消费加 `--json`） |
+| 积分流水（花了多少、花在哪） | `crab credits history [--limit N] [--offset N]`（变动 ±：消耗为负；`--json` 含 total） |
+| 查动作计价（如发一封外域邮件扣多少） | `crab credits pricing`（公开端点，无需登录） |
 | 列出已授权的 Agent 令牌 | `crab tokens list`（脚本消费加 `--json`） |
 | 撤销某个令牌（高危，先确认） | `crab tokens revoke <id>` |
-| 重新授权 / 调整 scope | `crab login --scopes mail.read`（浏览器确认，你只发起） |
+| 重新授权 / 调整 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 有意不开放 |
 
+积分命令需 `credits.read` scope（`account` 组含它）：退出码 4 报缺该 scope 时，
+引导 `crab login --scopes account` 重新授权。积分额度一律以**积分数**表述
+（100 积分 = $1.00，仅价格类口径用美元）；充值/下单是 Web 会话能力，CLI/Agent
+令牌不动账——用户要充值时引导网页账单页（crabcloud.cc/account/billing）。
 拿不准令牌 id 时先 `crab tokens list` 核对；`revoke` 只接受列表里的 id。
 
 ## 机器可读输出
 
 程序化消费时**始终加 `--json`**（`whoami --json` / `tokens list --json`）：
 
-- `whoami --json` → `{ actor, scopes, account: { username, displayName, … }, personalSpace, subscription, credits }`；
+- `whoami --json` → `{ actor, scopes, account: { username, displayName, … }, personalSpace, subscription, credits, apps }`；
 - `tokens list --json` → `[{ id, name, scopes, createdAt, lastUsedAt, expiresAt, revoked }]`：
   后续 `revoke` 用 `id`，向用户转述时用 `name` + `scopes`。
 
@@ -57,6 +72,15 @@ Crab Cloud 是用户的个人云底座：账号、订阅与积分是平台层，
 - **撤销令牌是高危操作**：先向用户复述目标令牌的名称与 scope，得到确认后再
   执行 `crab tokens revoke`；撤销立即生效，不可恢复（重新授权即可再建）。
 - **scope 最小化**：建议按需授权（只读场景 `crab login --scopes account.read`），
-  不要怂恿用户一次性给全量 scope。
-- 如实转述能力边界：邮箱 / 云文件 / 协作项目尚未上线，相关请求引导用户关注
-  后续版本，不要编造命令或输出。
+  不要怂恿用户一次性给全量 scope。`--scopes` 支持组名（`mail` = 读写搜删四项
+  整组）与单个 scope 混用；组目录见 `crab help`，可用组：account / mail /
+  storage（云盘，含素材与附件）/ collab / contacts。
+- 如实转述能力边界：协作尚未上线——相关请求如实说明，引导用户
+  用网页（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）操作，
+  不要猜命令、也不要试图直接调 API。

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

@@ -0,0 +1,74 @@
+---
+name: crabcloud-mail
+description: Read, search and send the user's Crab Cloud platform email (username@crabcloud.cc) through the `crab` CLI — list folders, read messages, full-text search, send mail, archive/trash/delete. Use this skill when the user asks to check, read, find, draft or send email on Crab Cloud ("看看我的邮箱", "读一下这封邮件", "帮我回复", "发邮件给…", "crab mail"), or asks what their mailbox looks like — even if they never say "crab" or "Crab Cloud" explicitly.
+---
+
+# Crab Cloud 邮箱（crab mail）
+
+用户的 Crab Cloud 账号自带平台邮箱 `username@crabcloud.cc`（用户名即地址本地部分）。
+本 skill 覆盖邮箱域的 agent 通道；账号/令牌管理见 `crabcloud` skill。云盘见
+`crabcloud-storage` skill（`crab storage …`），协作尚未上线——用户问到时如实说明，
+**不要猜命令**。
+
+## 第一步：确认可用
+
+- 运行 `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 按需最小化
+  重新授权（你只发起，不代批）。
+
+## 意图 → 命令映射
+
+| 用户意图 | 命令 |
+|---|---|
+| 看收件箱 / 各文件夹 | `crab mail list`（默认 inbox；`--folder sent\|drafts\|archive\|trash`） |
+| 只看未读 | `crab mail list --unread` |
+| 翻页 | `crab mail list --cursor <nextCursor>`（列表末尾会提示） |
+| 读某封邮件 | `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>` |
+
+拿不准邮件 id 时先 `crab mail list` / `crab mail search` 核对再操作。
+
+## 计费口径（必须如实转述）
+
+- **平台内互发免费**：收件人也是 `@crabcloud.cc` 地址时不消耗积分。
+- **外部出站 2 积分/封**：发送前向用户复述收件人与计费；退出码 7 = 积分不足，
+  告知用户不要自动重试。
+- 发送结果会报告 `消耗积分` 与失败数；部分失败时失败部分的积分自动退回
+  （`发送:partial` 标记）。
+
+## 机器可读输出
+
+程序化消费**始终加 `--json`**：
+
+- `mail list --json` → `{ items: [...], nextCursor }`，条目含
+  `id/folder/fromAddr/to/subject/snippet/isUnread/hasAttachments/createdAt`；
+- `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` 发出。
+- 附件：`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,8 +1,8 @@
 {
   "name": "@crabcloud/skills",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
-  "description": "Crab Cloud agent skills (SKILL.md) with a standalone installer — teach coding agents to operate the user's personal cloud via the crab CLI.",
+  "description": "Crab Cloud agent skills (SKILL.md) with a standalone installer \u2014 teach coding agents to operate the user's personal cloud via the crab CLI.",
   "bin": {
     "crab-skills": "dist/crab-skills.js"
   },