@crabcloud/skills 0.1.2 → 0.1.4

package/dist/skills/crabcloud/SKILL.md

@@ -15,9 +15,10 @@ Crab Cloud 是用户的个人云底座：账号、订阅与积分是平台层，
 
 ## 第一步：确认 CLI 可用
 
-- 运行 `crab --version` 确认已安装。命令不存在时让用户运行
-  `npx @crabcloud/cli init`（登录 + 安装本 skill 一步完成）；已装过但命令缺失
-  时运行 `npx @crabcloud/cli@latest init` 升级。
+- 运行 `crab --version` 确认已安装。注意 `crab init` 只做登录 + 安装 skill，
+  **不含命令本体**——本机没有 `crab` 命令时让用户 `npm i -g @crabcloud/cli@latest`
+  安装（已装旧版同款命令升级）；不想装全局则整段跳过，下文所有 `crab <命令>`
+  直接 `npx @crabcloud/cli <命令>` 等价执行（init 同样可 `npx @crabcloud/cli init`）。
 - `crab whoami` 报「未登录」或退出码 3 → 引导用户 `crab login`。登录走浏览器
   设备授权——授权页摆出全目录供用户勾选，**实际授予集由人定**，可能多于或少于
   `--scopes` 请求——**你只发起，不代批**；登录后先 `crab whoami` 核对实际

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

@@ -0,0 +1,96 @@
+---
+name: crabcloud-collab
+description: Work in the user's Crab Cloud collaboration spaces (协作空间) through the `crab` CLI — list spaces and members, create and complete tasks, push immutable execution records (Markdown + attachments/links), maintain the mutable task summary, and invite linked contacts. Use this skill when the user asks to create/update/check collaboration tasks or spaces on Crab Cloud ("建个任务", "协作空间里有什么", "把这个进度推送到任务", "邀请他进空间", "crab collab"), or wants an agent to record work progress into a task — even if they never say "crab" or "Crab Cloud" explicitly.
+---
+
+# Crab Cloud 协作（crab collab）
+
+协作是用户的任务协作应用：容器是协作空间（默认个人空间注册即有 + 独立付费
+空间），原子单位是任务。任务 = 不可改的执行记录流（GitHub issue 式：什么节点
+做了什么，人机同写），另有一个可随时覆盖的「摘要」字段表达当前态概览。本
+skill 覆盖协作域的 agent 通道；账号/令牌管理见 `crabcloud` skill，邮箱见
+`crabcloud-mail`，云盘见 `crabcloud-storage`。
+
+## 第一步：确认可用
+
+- 运行 `crab --version` 确认已安装。注意 `crab init` 只做登录 + 安装 skill，
+  **不含命令本体**——本机没有 `crab` 命令时让用户 `npm i -g @crabcloud/cli@latest`
+  安装（已装旧版同款命令升级）；不想装全局则整段跳过，下文所有 `crab <命令>`
+  直接 `npx @crabcloud/cli <命令>` 等价执行（init 同样可 `npx @crabcloud/cli init`）。
+- CLI 基于 npx 分发，**本机没有 `crab` 命令时，下文所有 `crab <命令>` 都可以
+  `npx @crabcloud/cli <命令>` 等价执行**（例如 `npx @crabcloud/cli collab tasks`）。
+- 未登录（退出码 3）引导用户 `crab login`。
+- **协作命令需要空间绑定**：授权时必须带 `--space`（`default` = 默认空间，
+  `space:<名称>` = 按名唯一命中）。含 collab scope 但没带 `--space` 会直接报
+  用法错误（退出码 2）。正确示例：
+  `crab login --scopes collab --space default`
+- 动作需要对应 scope：读（spaces/tasks/records/members）`collab.read`，写
+  （建任务/推送/完成/摘要/邀请）`collab.write`——一般整组授权 `--scopes collab`。
+- 退出码 4 有两种协作专属情形，处置都是重新授权：
+  - `collab_space_not_bound`：令牌没绑空间——按上面带 `--space` 重新 `crab login`；
+  - `collab_space_mismatch`：令牌绑的是别的空间——换绑到目标空间（`--space`
+    指对）重新授权。**不要**反复重试同一令牌。
+- 推送记录免费（不消耗积分）；建独立空间（5 积分）与扩容才计费，见「纪律」。
+
+## 空间怎么指（--space）
+
+所有落到一个空间的命令都接受 `--space <arg>`，`<arg>` 三种形态：
+
+1. `default` —— 用户的默认个人协作空间（注册即有）；
+2. `space:<名称>` —— 按名称唯一命中（active 空间）；
+3. 空间 id —— `crab collab spaces` 查到的 id。
+
+**缺省 `--space` 时**：只在一个空间则自动采用；多个则 CLI 列出候选并要求显式
+指定——不要瞎猜，先 `crab collab spaces` 看一眼再带上正确的 `--space`。
+
+## 意图 → 命令映射
+
+| 用户意图 | 命令 |
+|---|---|
+| 有哪些协作空间 | `crab collab spaces`（任务/成员计数、限额、独立空间名额） |
+| 建独立协作空间 | `crab collab space create <名称> [--allocation-mb 500]`（**消耗 5 积分**，见纪律） |
+| 空间里有什么任务 | `crab collab tasks [--space <arg>]`（倒序，含摘要/记录数；`--status open\|done`、`--q 关键字` 搜标题与记录正文） |
+| 任务详情 | `crab collab task <id>`（状态/摘要/记录数） |
+| 建任务 | `crab collab task create --space <arg> --title "..." --body "首条记录(Markdown)"`（也可 `--body-file <路径>`；附件 `--attach <fileId,...>`、链接 `--link <url,...>`） |
+| 读任务的来龙去脉 | `crab collab task records <id>`（倒序记录流，Markdown 源文；`--cursor` 翻更早） |
+| 推送工作记录 | `crab post <taskId> --body "做了什么(Markdown)"`（糖命令，等价 records 写入；免费） |
+| 任务做完了 | `crab collab task done <id>`（入流一条状态变更）；反悔 `crab collab task reopen <id>` |
+| 维护任务摘要 | `crab collab task summary <id> --text "当前态概览"`（可随时覆盖；`--clear` 清空；不入记录流） |
+| 谁在空间里 | `crab collab members [--space <arg>]` |
+| 邀人进空间 | `crab collab invite <username> [--space <arg>]`（**只能邀联系人中已关联的平台用户**，见纪律） |
+| 看协作活动 | `crab collab activity`（Agent 推送/读取、任务创建、摘要更新事件） |
+
+任务 id 从 `crab collab tasks` 拿；`crab post` 的 `<taskId>` 同源。
+
+## 机器可读输出
+
+程序化消费**始终加 `--json`**：
+
+- `collab spaces --json` → `{ spaces: [...], independentLimit, independentUsed }`，
+  条目含 `id / kind / name / status / taskCount / memberCount / limits`；
+- `collab tasks --json` → `{ tasks: [...], nextCursor }`，条目含
+  `id / title / status / summary / recordCount / latestRecordAt`（游标分页）；
+- `collab task records --json` → `{ records: [...], nextCursor }`，条目含
+  `id / kind / body / authorName / via / refs / createdAt`；
+- `post --json` → `{ recordId, via?: { token, eventId } }`（via.eventId 即该条
+  记录 id，可确定性回查）；
+- `collab task <id> --json` / `collab members --json` / `collab activity --json`
+  同构。
+
+## 纪律
+
+- **记录流不可改**：推上去就是历史，没有编辑/删除——推送前把内容写对；写错了
+  补一条更正记录，不要试图「撤回」。
+- **摘要是可变当前态**：表达「现在进展到哪」，不是流水账；每次推送记录后若
+  摘要已过时，顺手 `crab collab task summary` 刷新，让不看全程的人一眼看懂。
+- **建独立空间是付费动作（5 积分）**：先向用户复述名称与自分配存储（默认
+  500MB，占订阅总池），确认后再执行；`collab space create` 不要当作顺手操作。
+- **邀请有前置**：目标必须是联系人簿里已关联的平台用户（`crab contacts add`
+  站内地址自动关联）；报「只能邀请联系人中已关联的平台用户」时，先引导建联
+  系人，不要换名字硬试。
+- **附件引用不复制**：`--attach` 的 fileId 是云盘/空间已有文件的引用（≤10 个），
+  只能引用空间成员的云盘文件或本空间直传文件；跨空间文件会被 403 拒绝。
+- 单任务记录流上限 500 条（状态变更也占位）：任务粒度别太粗，做完就 `done`，
+  新工作开新任务。
+- 读记录流对 Agent 是一等审计事件（thread.read 入活动流）——正常读即可，但
+  不要在循环里无意义地反复拉全量记录。

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

@@ -12,9 +12,10 @@ description: Read, search and send the user's Crab Cloud platform email (usernam
 
 ## 第一步：确认可用
 
-- 运行 `crab --version` 确认已安装。命令不存在时让用户运行
-  `npx @crabcloud/cli init`（登录 + 安装本 skill 一步完成）；已装过但命令缺失
-  时运行 `npx @crabcloud/cli@latest init` 升级。
+- 运行 `crab --version` 确认已安装。注意 `crab init` 只做登录 + 安装 skill，
+  **不含命令本体**——本机没有 `crab` 命令时让用户 `npm i -g @crabcloud/cli@latest`
+  安装（已装旧版同款命令升级）；不想装全局则整段跳过，下文所有 `crab <命令>`
+  直接 `npx @crabcloud/cli <命令>` 等价执行（init 同样可 `npx @crabcloud/cli init`）。
 - CLI 基于 npx 分发，**本机没有 `crab` 命令时，下文所有 `crab <命令>` 都可以
   `npx @crabcloud/cli <命令>` 等价执行**（例如 `npx @crabcloud/cli mail list`）。
 - 未登录（退出码 3）引导用户 `crab login`。

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

@@ -1,20 +1,22 @@
 ---
 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。
 
 ## 第一步：确认可用
 
-- 运行 `crab --version` 确认已安装。命令不存在时让用户运行
-  `npx @crabcloud/cli init`（登录 + 安装本 skill 一步完成）；已装过但命令缺失
-  时运行 `npx @crabcloud/cli@latest init` 升级。
+- 运行 `crab --version` 确认已安装。注意 `crab init` 只做登录 + 安装 skill，
+  **不含命令本体**——本机没有 `crab` 命令时让用户 `npm i -g @crabcloud/cli@latest`
+  安装（已装旧版同款命令升级）；不想装全局则整段跳过，下文所有 `crab <命令>`
+  直接 `npx @crabcloud/cli <命令>` 等价执行（init 同样可 `npx @crabcloud/cli init`）。
 - CLI 基于 npx 分发，**本机没有 `crab` 命令时，下文所有 `crab <命令>` 都可以
   `npx @crabcloud/cli <命令>` 等价执行**（例如 `npx @crabcloud/cli storage ls`）。
 - 未登录（退出码 3）引导用户 `crab login`。
@@ -29,22 +31,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 +60,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 +87,11 @@ restore/purge 直接用文件名即可）；命中多个或查不到时按字面
   确认后再执行；收回用 `unpublish`（已缓存浏览器至多 5 分钟内失效）。
 - **share 是可控分享**：默认 7 天有效、可选提取码、随时 `unshare` 撤销；加密
   对象的分享链接自带解密钥匙（`#` 后缀）——泄露链接即泄露文件，外发前向
-  用户复述有效期与提取码设置，确认后再执行。
+  用户复述有效期与提取码设置，确认后再执行。收件人在浏览器打开加密分享链接
+  会看到内联解密落地页（图片/视频/音频/PDF/文本直接预览，其余类型仅下载）。
+- **提取码错误重试有服务端限流**：同一链接+来源 IP 错误次数超限返回 429
+  （退出码 1，消息「尝试过于频繁」）——**不要程序化暴力重试**，如实转述用户
+  等待即可；凭链接下载时提取码用 `--passcode` 正确携带。
 - **purge 是彻底删除**，不可恢复；用户没明说「彻底删除」时一律用 `rm`
   （回收站保留 7 天可找回）。
 - 邮件附件与用户上传同账：水位告急时用 `quota` 分项定位来源再建议清理。

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@crabcloud/skills",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
-  "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.",
+  "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.",
   "bin": {
     "crab-skills": "dist/crab-skills.js"
   },