red-bucket 技能

此技能指導 AI 代理如何與 red-bucket 伺服器互動。red-bucket 是一個 AI 代理資產（技能、MCP 配置、指令如 CLAUDE.md 和 AGENTS.md、子代理、外掛）的中樞，以 user/bucket 命名空間組織，並支援在 codex、claude、agents 和 openclaw 之間進行即時跨框架格式轉換。

代理防護與不變量

認證： 所有寫入操作以及存取使用者擁有的私有儲存庫都需要 Authorization: Bearer <token>。公開儲存庫的讀取是匿名的，不需要標頭。
憑證安全： 切勿將密碼、API 令牌或機密列印、記錄或洩漏到輸出或使用者對話記錄中。
私有儲存庫 404 不變量： 任何來自未經認證的呼叫者或非擁有者對私有儲存庫或其子資源的請求都必須回傳 HTTP 404 Not Found（永遠不要回傳 403 Forbidden）。非擁有者無法區分私有儲存庫是否存在。
配額與限制：
- 預設儲存庫配額：每個使用者 5 個儲存庫（超過回傳 403 並帶有代碼 bucket_quota_exceeded）。
- 儲存庫儲存限制：每個儲存庫 10MB（超過回傳 413 並帶有代碼 bucket_storage_exceeded）。
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. 在沒有此技能的情況下安裝儲存庫

使用 Accept: text/plain 標頭對 GET .../install-script?target=<harness> 發送請求，會回傳一個自包含的 Node 程式。將回應體儲存為 rb-install.mjs 並執行 node rb-install.mjs。同樣僅依賴 Node 環境，同樣支援 RED_BUCKET_URL / RED_BUCKET_DEST 覆蓋。

（對於私有儲存庫，沒有可貼上的公開程式：請改用帶有 Authorization: Bearer <token> 標頭的 GET .../translated 請求，或在使用 rb.mjs install 時先登入。）

登入與令牌存放位置

讀取公開儲存庫不需要任何東西。所有寫入操作 — 建立儲存庫、上傳資產、開啟議題或拉取請求 — 都需要一個 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> 傳送。

在使用來源作為鍵之前，請先正規化該來源，無論是寫入還是查詢時都要這麼做：將 scheme 和 host 轉換為小寫，刪除尾隨斜線，當埠號是 scheme 的預設值時刪除它。因此 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. 儲存它 到上述路徑，並只顯示 Signed in as <username>.。

登出

使用令牌對 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": "General development agent skills",
  "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: Perform arithmetic calculations\n---\n\n# Calculator Skill\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": "Bug in calculator skill translation",
  "body": "When t"
}

回應： 201 Created，帶有 Location: ... 和 Issue 物件。

回覆議題：

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

{
  "body": "This is a bug report.  I found an issue with..."
}

回應： 201 Created，帶有 Comment 物件。

列出議題：
```
GET /api/v1/users/{username}/buckets/{bucket}/issues
```
可選查詢參數：state（open、closed）、sort（created、updated）、direction（asc、desc）。

8. 拉取請求

建立拉取請求：

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

{
  "title": "Add new calculator skill",
  "body": "This PR adds...",
  "head_bucket": "alice/dev-skills",
  "base_bucket": "alice/dev-skills"
}

合併拉取請求：

POST /api/v1/users/{username}/buckets/{bucket}/pulls/{pull_id}/merge
Authorization: Bearer <token>

關閉拉取請求：

POST /api/v1/users/{username}/buckets/{bucket}/pulls/{pull_id}/close
Authorization: Bearer <token>

常見錯誤與故障排除

常見 HTTP 錯誤碼

代碼	意義	常見原因
`400`	錯誤請求	JSON 格式錯誤、遺失必填欄位
`401`	未經授權	遺失或無效的 `Authorization` 標頭
`403`	禁止存取	配額超標（`bucket_quota_exceeded`）或操作不允許
`404`	找不到	儲存庫或資產不存在（私有儲存庫總是回傳 404）
`409`	衝突	儲存庫名稱已被使用（`bucket_name_taken`）
`413`	承載過大	儲存庫超過 10MB 限制
`422`	無法處理的實體	資產驗證失敗（`validation_failed`）
`429`	請求過多	速率限制。減慢速度。`Retry-After` 標頭包含重試前的秒數。

資產驗證

上傳資產時，伺服器會根據儲存庫的框架範本進行驗證。常見的驗證錯誤包括：

SKILL.md missing：技能類型需要 SKILL.md 檔案。
Invalid harness: ...：指定的來源框架無效。
File size exceeds limit：單個檔案超過儲存庫限制。
Duplicate path：資產包含重複的檔案路徑。

診斷命令

GET /api/v1/health — 伺服器正常執行中。
GET /api/v1/templates — 列出可用的範本。
GET /api/v1/translation-matrix — 顯示支援的來源與目標框架對。

安全考量

令牌處理 (OWASP 最佳實務)

傳輸中： 所有 API 端點僅限 HTTPS。務必建立 TLS 連線。
儲存中： 如上所述，令牌檔案使用限制性權限（0600）進行保護。切勿在日誌、環境變數或可公開存取的儲存庫中儲存令牌。
使用中： 使用 Authorization: Bearer <token> 標頭傳送。切勿在 URL 查詢字串或請求體中包含令牌。
生命週期： 令牌可以透過伺服器端撤回（登出）或過期來失效。務必處理 401 回應，並提示使用者重新認證。
稽核： 使用者可以透過其個人資料檢視自己的有效會話。如果懷疑令牌被洩露，請提醒使用者登出所有裝置。
速率限制： 登入和裝置授權端點受到限制，以防止暴力破解和列舉攻擊。

使用者的安全注意事項

切勿與任何人分享您的令牌。
如果您懷疑令牌被洩露，請登出並變更密碼。
在每台裝置上使用唯一的令牌；不要在多個系統間複製 auth.json。
在 https://redbucket.store/settings 檢視您的有效會話。

參考資料

REST API 規格： 公開的 API 文件位於 https://redbucket.store/api/v1/docs（OpenAPI 3.0）
來源碼： https://github.com/370025263/red-bucket
支援： 在 GitHub 儲存庫上開啟議題或拉取請求
授權： MIT

370025263/red-bucket

red-bucket 是什麼？

在你喜歡的 AI 中提問

說明文件

red-bucket 技能

代理防護與不變量

三名稱規則

安裝與探索

1. 代理技能安裝（透過 `npx skills`）

2. 附帶的客戶端：`scripts/rb.mjs`

3. 在沒有此技能的情況下安裝儲存庫

登入與令牌存放位置

令牌的存放位置

取得令牌：瀏覽器移交方式

登出

沒有 red-bucket MCP 伺服器

使用者端流程與 API 操作

1. 使用者註冊、登入和個人資料

2. 從範本建立儲存庫

3. 上傳資產

4. 匿名瀏覽與翻譯後擷取

5. 執行安裝腳本

6. 複製資產到自己的儲存庫（來源追蹤）

7. 議題與留言

8. 拉取請求

常見錯誤與故障排除

常見 HTTP 錯誤碼

資產驗證

診斷命令

安全考量

令牌處理 (OWASP 最佳實務)

使用者的安全注意事項

參考資料

相關技能

steipete/notion

langchain-ai/langchain

bytedance/podcast-generation

composiohq/twitter-algorithm-optimizer

composiohq/competitive-ads-extractor

upstash/context7

在你喜歡的 AI 中提問

說明文件

red-bucket 技能

代理防護與不變量

三名稱規則

安裝與探索

1. 代理技能安裝（透過 npx skills）

2. 附帶的客戶端：scripts/rb.mjs

3. 在沒有此技能的情況下安裝儲存庫

登入與令牌存放位置

令牌的存放位置

取得令牌：瀏覽器移交方式

登出

沒有 red-bucket MCP 伺服器

使用者端流程與 API 操作

1. 使用者註冊、登入和個人資料

2. 從範本建立儲存庫

3. 上傳資產

4. 匿名瀏覽與翻譯後擷取

5. 執行安裝腳本

6. 複製資產到自己的儲存庫（來源追蹤）

7. 議題與留言

8. 拉取請求

常見錯誤與故障排除

常見 HTTP 錯誤碼

資產驗證

診斷命令

安全考量

令牌處理 (OWASP 最佳實務)

使用者的安全注意事項

參考資料

相關技能

steipete/notion

langchain-ai/langchain

bytedance/podcast-generation

composiohq/twitter-algorithm-optimizer

composiohq/competitive-ads-extractor

upstash/context7

1. 代理技能安裝（透過 `npx skills`）

2. 附帶的客戶端：`scripts/rb.mjs`