ShareOut 技能
ShareOut 能將檔案轉換為可共享的網路成品，支援持久資料、即時協作、檔案儲存、整合和自動化。它支援 HTML 應用程式以及 CSV、Markdown、JSON 和 TXT 檢視器。
這是規範性技能。對於每個 ShareOut 任務，都應首先載入此檔案。
版本檢查 — 強制性第一步驟
在執行任何其他操作之前，請確認您擁有最新的技能。此檔案 frontmatter 的 version 為您目前持有的版本 (目前為 2.21.0)。
GET https://shareout.site/v1/skill/version→{ "version": "...", "updated_at": "..." }。- 如果傳回的
version比此檔案 frontmatter 的version更新，則表示您的版本已過時：請下載GET https://shareout.site/v1/skill(完整技能檔案夾的 zip)，解壓縮它，丟棄舊的副本，然後從解壓縮的檔案繼續。 - 如果版本相符，則繼續。
請勿跳過此檢查。使用過時的技能會導致錯誤的端點和行為。
方案模型
ShareOut 有兩個方案：
| 方案 | 使用此技能行為 |
|---|---|
| 個人 (Personal) | 僅使用這個基礎技能。建立、發布、更新、自動化和管理使用者自己的成品。 |
| 團隊 (Teams) | 首先使用這個基礎技能，然後載入 Teams 覆蓋層以進行工作區管理或僅限 Teams 的功能。 |
Teams 是附加功能。切勿使用 Teams 覆蓋層來代替這個基礎技能。
代理載入協議
- 從此檔案開始。
- 如果使用者提及團隊、工作區、成員、內部工作區共享、子網域、工作區風格指南、工作區排程或管理員控制項，請詢問他們是否使用 Teams 方案 (如果尚未明確)。
- 如果使用者不使用 Teams，請保持在個人模式，不要載入或套用僅限 Teams 的指令。
- 如果使用者正在使用 Teams，請載入 team/SKILL.md。如果工作區 slug/id 和 token 可用，請擷取
GET /v1/skill?workspace={slugOrId}— 該 zip 包含一個額外的workspace-context.md，其中包含工作區規則。 - 使用 INDEX.md 按需載入詳細檔案。
首要問題
在建議實作方案之前，請先確定：
- 他們正在建立什麼？儀表板、表單、報告、工具、文件、資料網格、簡報或自動化。
- 誰會使用它？只有擁有者、受邀者、團隊工作區或一般大眾。
- 它需要什麼資料？無、簡單狀態、結構化記錄、檔案、即時外部資料或即時協作。
- 發布後應該發生什麼事？共享連結、收集資料、發送通知、排程交付、指標警報、接收並處理入站電子郵件，或讓檢視者與 AI 聊天。
模式路由器
資料選擇
選擇最適合的最小儲存方式：
簡單狀態：主題、篩選器、上次開啟 -> sdk.json
結構化記錄：任務、提交、訂單 -> sdk.table()
即時編輯：文件、白板、多人 UI -> sdk.realtime()
檔案：圖片、PDF、附件 -> sdk.blobs
即時外部系統：REST、BigQuery、Mixpanel、倉儲 -> sdk.connection / live-data
請勿將資料選擇與帳戶方案混淆。sdk.json、sdk.table() 和 sdk.realtime() 是資料儲存，而不是計費方案。
SDK 載入
<head>
<link rel="stylesheet" href="https://shareout.site/sdk/shareout.css">
<script src="https://shareout.site/sdk/shareout-ui.js" defer></script>
<script src="https://shareout.site/sdk/shareout.js"></script>
</head>
<script>
(async () => {
const sdk = await ShareOut.create();
})();
</script>
規則：
- 在呼叫
ShareOut.create()之前載入https://shareout.site/sdk/shareout.js。 - 優先使用
await ShareOut.create()而非new ShareOut()，以便內嵌的 Bearer token 準備就緒。 - 已發布的 HTML 在
{hex}.shareoutcdn.site上的沙箱 iframe 中執行；請使用 SDK 方法，不要使用原始fetch到/v1/data/...。請參閱 sdk/live-data.md。 - 連結
https://shareout.site/sdk/shareout.css並在編寫自訂 CSS 之前使用.so-類別。請參閱 modules/ui/overview.md。 - 請勿使用
cdn.jsdelivr.net的 ShareOut SDK URL。
HTML 成品規則
無論 HTML 成品是否帶有 ShareOut 的結構標記，皆可運作 — 發布永遠不會被阻止。但成品宣告的越多，視覺編輯器 就能對其做越多操作 (大綱導航、內嵌編輯、新增/移除列)。目標是預設為「編輯器就緒」；只有當刻意要建立一次性的靜態頁面時才跳過它。
編輯器就緒檢查清單 (編輯器會檢查的項目)：
- 文件
head中的一個script type="shareout/manifest"標籤，包含有效的 JSON。 - 在 manifest
sources中宣告所使用的每個sdk.json鍵和sdk.table()名稱。 - 動態內容帶有
data-shareout-binding，且每個 binding 都引用一個已宣告的 source。 - 頁面使用
data-shareout-page(驅動編輯器大綱)；重複內容使用data-shareout-template。 - 互動目標已解析：
data-shareout-link/data-shareout-action指向真實的頁面/區段/模態視窗/標籤頁；模態視窗具有開啟觸發器；表單具有提交動作。 - 在
sources上宣告default範例資料 —json、tables以及connections(即時連接器，如 BigQuery/Snowflake/Sheets：sources.connections.<name>.default是一個範例行陣列)。視覺編輯器預覽資料時不會進行即時擷取或查詢 (它會從這些預設值 (或空值) 解析所有 SDK 讀取 — 包括sdk.connection(...).query())，因此一個將其 UI 建立在await sdk.table(...).exec()/ 連接器查詢之上的成品仍然可以呈現和編輯。如果某個 source 沒有default，則預覽為空。
每次發布 HTML 成品時，都會傳回一個建議性的 editor_readiness 設定檔 (請參閱 api/artifacts.md)，該設定檔會評估這些項目並說明每個差距會停用哪些功能。向使用者分享一行摘要，但將其視為指導，而非強制條件 — 他們可以完全發布他們想要的內容。
完整規格：core/html-spec/overview.md。
設計品味
編輯器就緒關乎結構，而非外觀。外觀是一個單獨的、經過深思熟慮的決定 — 而 AI 建置頁面的預設值是「模板化且通用的」。在開始建立任何視覺化內容之前，請閱讀 modules/ui/taste.md：其中濃縮了如何產出看起來專業設計而非自動生成的成品。簡短版本：
- 使用設計系統 (
.so-類別 + token) — 它提供了品牌字體、溫暖的淺色調色盤以及和諧的間距/陰影，因此您可以免費繼承良好的品味。請參閱 modules/ui/overview.md。 - 品味是克制： 一種強調色、一套字體系統、每個畫面一個主要操作、大量的留白，以及只有在有理由時才使用動畫。
- 避免 AI 常見的劣質跡象： 紫色/霓虹光暈、三個等寬卡片列、「眉毛」文字泛濫、完美假數字、行銷陳腔濫調、缺少空白/錯誤狀態。完整的禁止清單和發布前檢查清單位於 modules/ui/taste.md。
成品類型
ShareOut 會根據 MIME 類型或副檔名自動偵測類型：
| 類型 | 副檔名 | 用途 |
|---|---|---|
html | .html, .htm | 完整的 SDK 應用程式、儀表板、工具、簡報 |
csv | .csv | 可排序/可篩選的資料網格 |
markdown | .md, .markdown | 具有渲染 HTML 和目錄的文件 |
json | .json | 可折疊的樹狀檢視器 |
txt | .txt | 純文字/日誌檢視器 |
詳細資訊：api/artifact-types.md。
首次執行 — 取得 Token
每個需要驗證的動作都需要一個 token。如果 ~/.shareout/credentials 尚不存在，則使用者沒有帳戶 — 請在發布或任何其他需要驗證的呼叫之前建立一個：
POST https://shareout.site/v1/auth/create-account(唯一的非驗證端點，無需 body) →{ "token": "so_…", "user_id": "usr_…" }。- 將
token儲存到~/.shareout/credentials，格式為{ "token": "so_…" }(chmod 600)。 - 後續所有請求皆使用
Authorization: Bearer so_…。
帳戶建立有 IP 速率限制 (code: RATE_LIMIT_EXCEEDED, 429)。該帳戶是匿名且無頭的 — 發布不需要電子郵件。
然後詢問使用者是否要連結 Gmail/Google。 引導帳戶沒有電子郵件，因此只能透過儲存的 token 使用。連結電子郵件可讓他們登入網頁 UI，網址為 https://shareout.site (首頁儀表板、視覺編輯器、自助 API token)。提供兩種途徑：
- Google： 在瀏覽器中開啟
GET https://shareout.site/v1/auth/link-google(Bearer token) 以連結他們的 Google 帳戶。 - 電子郵件驗證碼：
POST /v1/auth/link-email/start{ "email" }→POST /v1/auth/link-email/verify{ "email", "code" }(6 位數驗證碼，10 分鐘有效期)。
如果他們拒絕，僅使用 token 的流程仍可繼續運作。完整的入門和連結參考請參閱 auth.md。
發布
ShareOut 受到 Cloudflare 保護。Python 的 requests 可能會觸發 1010 封鎖。請以您喜歡的方式建置 payload，然後 pipe 到 curl：
TOKEN=$(python3 -c "import json,os; print(json.load(open(os.path.expanduser('~/.shareout/credentials')))['token'])")
python3 build_payload.py | curl -sS -X POST 'https://shareout.site/v1/publish' \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
--data-binary @-
完整 API：api/overview.md。
Teams 界限
個人成品仍然可以是私有的、與協作者共享、公開或不公開列出。僅為 Teams 方案的工作區功能載入 Teams 文件：
- 工作區成員和角色。
- 內部工作區可見性 (
visibility: "workspace")。 - 依電子郵件/網域劃分的工作區成員資格政策。
- 工作區子網域。
- 用於風格指南的工作區上下文檔案。
- 工作區層級的排程、自動化、功能標誌和管理員檢視。
重要的術語區別：
| 術語 | 含義 |
|---|---|
access_policy | 列層級的成品資料過濾：每位檢視者只能看到允許的行。請參閱 core/access-policy.md。 |
| 工作區成員資格政策 | Teams 電子郵件/網域成員規則：誰可以加入工作區。請參閱 team/SKILL.md。 |
| 協作者角色 | 成品層級的 owner、editor、viewer。 |
| 工作區角色 | Teams 工作區的 owner、admin、member。 |
版本檢查
在每個任務之前執行 強制性版本檢查。有三種等效方法可以比較您持有的 version 與線上版本：
GET https
…