370025263/red-bucket

red-bucket 技能

本技能指导 AI 代理如何与 red-bucket 服务器进行交互。red-bucket 是一个 AI 代理资产（技能、MCP 配置、指令如 CLAUDE.md 和 AGENTS.md、子代理、插件）中心，按 user/bucket 命名空间组织，并具有在 codex、claude、agents 和 openclaw 之间进行即时跨工作台格式翻译的功能。

---

代理护栏与不变规则

1. 身份验证： 所有写操作以及访问用户拥有的私有存储桶都需要 Authorization: Bearer <token>。读取公共存储桶是匿名的，无需请求头。
2. 凭证安全： 切勿将密码、API 令牌或密钥打印、记录或泄露到输出或用户对话记录中。
3. 私有存储桶 404 不变规则： 任何对私有存储桶或其子资源的请求，如果来自未经身份验证的调用者或非所有者，必须返回 HTTP 404 Not Found（绝不能返回 403 Forbidden）。非所有者无法区分私有存储桶是否存在。
4. 配额与限制：
   • 默认存储桶配额：每个用户 5 个存储桶（超出则返回 403，错误码为 bucket_quota_exceeded）。
   • 存储桶存储限制：每个存储桶 10MB（超出则返回 413，错误码为 bucket_storage_exceeded）。
5. API 范围： 所有端点均位于 /api/v1/ 下。

---

三操作名称规则

切勿混淆或混合以下三种操作：

• copy (POST /api/v1/users/{username}/buckets/{bucket}/copies)：将资产从可读的源存储桶复制到您自己的目标存储桶，并附带来源历史。返回一个 InstallRecord JSON 对象。
• install-script (GET /api/v1/users/{username}/buckets/{bucket}/install-script)：返回可执行的 shell 脚本文本，用于下载并将翻译后的资产放置到本地文件系统。
• translated fetch (GET .../translated)：获取原始翻译后的字节或按需为指定目标工作台转换的 zip 归档文件。

---

安装与发现

1. 代理技能安装（通过 npx skills）

要将此技能安装到代理环境中：

# 全局安装以供代理访问
npx skills add 370025263/red-bucket --skill red-bucket -g -y

# 列出可用技能但不安装
npx skills add 370025263/red-bucket --list

2. 捆绑的客户端：scripts/rb.mjs

此技能自带客户端。它只需要 Node 18+ 且无其他依赖 —— 不需要 sh、curl、unzip、jq 或 npm install。优先使用它而不是手动编写 HTTP 调用；它已经正确地处理了源地址规范化、文件权限和原子写入。

node <skill-dir>/scripts/rb.mjs login   --client claude
node <skill-dir>/scripts/rb.mjs status
node <skill-dir>/scripts/rb.mjs logout
node <skill-dir>/scripts/rb.mjs install alice/tools --target claude
node <skill-dir>/scripts/rb.mjs create  alice/tools --visibility private --description "my kit"
node <skill-dir>/scripts/rb.mjs upload  alice/tools ./my-skill --type skill --harness claude --path skills/my-skill

login 打印链接，然后等待 --wait 秒（默认 20）让浏览器响应。如果您的 shell 工具有超时，那没问题：超时时它会以退出码 0 退出，将待处理代码保留在认证文件旁边的 pending.json 中，并提示用户。告诉用户批准，然后再次运行 login 或 status；令牌将被收集并保存。在第一个代码仍然有效时不会发出第二个代码，所以永远不要通过杀死进程并重新开始来“重试”。

install 写入当前目录；--dest DIR 或 $RED_BUCKET_DEST 将其放置到其他位置。--origin URL 或 $RED_BUCKET_URL 指向自托管服务器。登录后即可使用私有存储桶 —— 相同的命令，使用存储的凭证。

create 和 upload 是发布端。upload 将本地目录下的每个文件作为一个资产发送：文本文件作为文本，其他所有内容作为 base64，根目录为 --path（默认：目录自身的名称）。--type 指定资产的类型（skill, mcp, instructions, subagent, plugin），--harness 指定它是为哪个工作台编写的 —— 服务器会据此进行翻译。服务器会验证资产，客户端会准确打印出它所反对的内容，例如 validation failed: SKILL.md: SKILL.md missing。两者都需要登录。优先使用它们而不是手动构建 POST .../assets 主体：下面的原始端点是契约，客户端是工具。

3. 在没有此技能的情况下安装存储桶

GET .../install-script?target=<harness> 配合 Accept: text/plain 返回一个独立的 Node 程序。将主体保存为 rb-install.mjs 并运行 node rb-install.mjs。同样仅依赖 Node，同样支持 RED_BUCKET_URL / RED_BUCKET_DEST 覆盖。

（对于私有存储桶，没有可粘贴的公共程序：请改用带有 Authorization: Bearer <token> 的 GET .../translated，或者在登录后直接使用 rb.mjs install。）

---

登录以及令牌的存储位置

读取公共存储桶不需要任何操作。所有写操作——创建存储桶、上传资产、提交 issue 或 pull request——都需要 bearer 令牌。

切勿要求用户提供他们的 red-bucket 密码。 请使用下面的浏览器交接方式。这是代理获取令牌的唯一授权方式。

令牌的存储位置

$RED_BUCKET_AUTH                                     如果设置了，则使用该确切文件
%APPDATA%\red-bucket\auth.json                       在 Windows 上
${XDG_CONFIG_HOME:-~/.config}/red-bucket/auth.json   在其他所有平台上

首先在这些位置查找。如果此源已有一个有效条目，则使用它——不要再次将用户送回到浏览器去获取他们已经授予您的令牌。

目录模式 0700，文件模式 0600。原子写入（先创建同一目录下的临时文件，然后重命名），这样中断的写入不会留下半截文件。按源地址键控的形状，以便自托管服务器和公共服务器可以共存：

{
  "version": 1,
  "hosts": {
    "https://redbucket.store": {
      "username": "stone91",
      "token": "...",
      "created_at": "2026-09-03T04:07:19Z",
      "client": "claude"
    }
  }
}

按以下顺序解析身份：如果设置了 $RED_BUCKET_TOKEN，则使用它；否则，使用该文件中键与您正在通信的源地址相匹配的条目；最后使用匿名身份。将其作为 Authorization: Bearer <token> 发送。

在将源地址用作键之前，请先对其进行规范化处理，无论是在写入时还是查找时：将协议和主机转换为小写，去掉尾部的斜杠，如果端口是协议的默认端口则去掉端口。因此，https://RedBucket.store:443/ 和 https://redbucket.store 是一个键，而不是三个。跳过此步骤，您将把用户再次送回到浏览器去获取您已有的令牌，并留下一个重复的条目。

如果文件无法解析，或者 version 是您无法识别的数字，则将其视为无凭证——回退到匿名身份，并告知用户文件似乎有问题。切勿删除或覆盖您无法读取的文件；它可能包含其他工具的令牌。

一次性读取、更改和写入整个文件，并保持操作窗口短小。两个工作台同时登录，则两者都读取、两者都写入，较慢的一个会擦除另一个的条目。上述的临时文件然后重命名操作可以防止残缺文件，但不能防止丢失更新。

切勿打印令牌，切勿将其回显到对话记录中，切勿将其写入仓库，切勿将其放在用户可以在其滚动历史中看到的 shell 命令中。

获取令牌：浏览器交接

令牌由服务器生成并直接传递给您的进程。它永远不会经过对话。

1. 启动它。

POST /api/v1/auth/device
{"client": "claude"}

201 返回 device_code、user_code、verification_url_complete、expires_in (600) 和 interval (5)。

device_code 是秘密部分——它保留在您的进程内部。user_code 是供人类阅读的短代码。

2. 向人类展示链接。 类似这样：

打开此链接以登录或创建账户： https://redbucket.store/link/BQ7K-2M4X 页面应显示代码 BQ7K-2M4X。我会等待。

用户在浏览器中打开它，如果尚未登录则登录，然后会看到一个屏幕，显示您的客户端名称和它们将授予的权限。用户按下“授权”或“拒绝”。

3. 轮询，速度不超过 interval 秒：

POST /api/v1/auth/device/token
{"device_code": "..."}

• {"status": "pending"} —— 继续等待。
• {"status": "denied"} —— 用户拒绝了。停止，并明确告知。
• {"status": "approved", "token": ..., "user": {...}} —— 您已获得令牌。
• 404 —— 代码已过期，或已被收集。提供重新开始的选项。device_code 是单次使用的；第二次成功的轮询始终返回 404。

4. 保存它 到上面的路径，并仅显示 已登录为 <用户名>.。

登出

POST /api/v1/auth/logout 配合令牌将使该令牌在服务器端失效。然后从认证文件中删除该主机的条目。两者都要执行；只做一个而不做另一个，要么会在服务器上留下一个活动的令牌，要么会在磁盘上留下一个已失效的令牌。

没有 red-bucket MCP 服务器

red-bucket 中的 mcp 是一种存储桶可以持有的资产类型，而不是我们运行的服务器。此技能与 /api/v1/ 通信就是整个客户端集成。不要去寻找要连接的 MCP 端点。

---

用户端流程与 API 操作

1. 用户注册、登录与个人资料

• 注册：

  POST /api/v1/auth/register
  Content-Type: application/json
  
  {
    "username": "alice",
    "email": "[email protected]",
    "password": "strongpassword123"
  }
  

  • 响应： 201 Created，包含 Location: /api/v1/users/alice 和公共 User 对象（密码使用 Argon2id 哈希；注册时不颁发令牌）。

• 登录：

  POST /api/v1/auth/login
  Content-Type: application/json
  
  {
    "email": "[email protected]",
    "password": "strongpassword123"
  }
  

  • 响应： 200 OK，包含 {"token": "<opaque_token>", "token_type": "bearer", "user": { ... }}。

• 获取个人资料（me）：

  GET /api/v1/users/me
  Authorization: Bearer <token>
  

  • 响应： 200 OK，包含用户详细信息（包括 email、bucket_quota、bucket_count）。

---

2. 从模板创建存储桶

在已验证用户命名空间下创建一个存储桶：

POST /api/v1/users/{username}/buckets
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "dev-skills",
  "visibility": "public",
  "description": "通用开发代理技能",
  "template": "claude"
}

• 允许的模板：codex、agents、claude、openclaw（省略则为空存储桶）。此列表会增长；GET /api/v1/templates 是实时列表。
• 可见性：public 或 private（默认为 private）。
• 响应： 201 Created，包含 Location: /api/v1/users/{username}/buckets/{name} 和 Bucket JSON。
• 错误： 403（如果超过 5 个存储桶则返回 bucket_quota_exceeded），409（bucket_name_taken）。

---

3. 上传资产

上传资产并执行格式验证和配额强制：

POST /api/v1/users/{username}/buckets/{bucket}/assets
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "skill",
  "source_harness": "claude",
  "path": "skills/calculator",
  "files": [
    {
      "path": "SKILL.md",
      "content_text": "---\nname: calculator\ndescription: 执行算术计算\n---\n\n# 计算器技能\n"
    }
  ]
}

• 资产类型：skill、mcp、instructions、subagent、plugin。
• 源工作台：claude、codex、agents、openclaw。此列表会增长；GET /api/v1/translation-matrix 是实时列表。切勿仅仅因为某个工作台在此文件中缺失而拒绝用户命名的它——让服务器来回答。
• 文件内容可以以 content_text（UTF-8）或 content_base64 提供。
• 响应： 201 Created，包含 Location: /api/v1/users/{username}/buckets/{bucket}/assets/{asset_id}。
• 错误： 413（如果存储桶超过 10MB 则返回 bucket_storage_exceeded），422（validation_failed，包含特定规则和路径违反信息）。

---

4. 匿名浏览与翻译后获取

• 浏览存储桶（公共/匿名）：

  GET /api/v1/users/{username}/buckets/{bucket}
  

• 浏览文件树与 Blob：

  GET /api/v1/users/{username}/buckets/{bucket}/tree
  GET /api/v1/users/{username}/buckets/{bucket}/blob/{*path}
  

• 为指定目标工作台获取翻译后的完整存储桶：

  GET /api/v1/users/{username}/buckets/{bucket}/translated?target=codex
  

  • 响应： 200 OK（二进制 zip 归档，请求头 X-Red-Bucket-Lossy: true|false）。

• 获取翻译后的单个资产：

  GET /api/v1/users/{username}/buckets/{bucket}/assets/{asset_id}/translated?target=codex
  

  • 响应： 200 OK（原始翻译后字节或 zip 归档）。

---

5. 运行安装脚本

检索为指定目标工作台生成的 shell 安装脚本：

GET /api/v1/users/{username}/buckets/{bucket}/install-script?target=claude
Accept: text/plain

• 响应： 200 OK，包含原始 shell 脚本文本。
• 在客户端执行以下载翻译后的 zip 归档并将文件放置到本地工作台目录中。

---

6. 将资产复制到自己的存储桶（来源跟踪）

将资产从源存储桶复制到您自己的目标存储桶：

POST /api/v1/users/{username}/buckets/{dest_bucket}/copies
Authorization: Bearer <token>
Content-Type: application/json

{
  "source_username": "bob",
  "source_bucket": "public-skills",
  "source_asset_id": 12,
  "dest_path": "skills/calculator"
}

• 响应： 201 Created，包含 Location: /api/v1/users/{username}/buckets/{dest_bucket}/copies/{copy_id} 和 InstallRecord JSON 对象。
• 验证源资产，检查 10MB 配额，并记录来源。

---

7. 议题与评论

• 创建议题：

  POST /api/v1/users/{username}/buckets/{bucket}/issues
  Authorization: Bearer <token>
  Content-Type: application/json
  
  {
    "title": "计算器技能翻译中的错误",
    "body": "当 t
  

…

[为翻译而截断]