syokan 是做什麼的?
syokan(召喚)是一個動詞 — LLM 召喚豐富的 UI。 當使用者說「syokan X」(中文:呼召 X / 招喚 X),就是要求將該資料召喚成一個視圖。底層是基於 schema 驅動的視圖層:不用撰寫 JSX,只需唸出一段 JSON 咒語 — 由目錄組件構成的樹狀結構 — syokan 就會用預先定義的組件將其渲染出來。 你的工作是將資料組裝成一個信封(envelope),然後透過 POST 發送給 syokan。 在行文中,請將 syokan 當作一個純及物動詞使用(絕不要說「do syokan」或「syokan する」—— syokan 可以獨立使用)。
如果 syokan 尚未安裝(執行 syokan --help 失敗),或者使用者說「onboarding」、「set it up」或「first time using it」,請引導他們按照 references/onboarding.md 進行,直到建立第一個快照。請勿在未經同意的情況下靜默執行會改變環境的操作(如安裝):請回報尚未安裝,並在使用者核准後再執行(絕不自行安裝)。
不可協商的原則
- 快照是暫時性的:發布的快照不保證持久性。只能存放可重建的、暫時性的資料(例如今天的 RSS、進行中的審查等)。對於重複使用的佈局,請儲存一個模板以便重現(模板是持久保存的——請參考「用模板實現可重複性」)。
- 僅限 JSON:伺服器只接受 JSON 信封。原始 Markdown 或純文字會被拒絕。若要顯示文章,請將其包裝在
MarkdownDoc或PlainText節點中。 - 嚴格的 schema:屬性會經過嚴格驗證。不在 schema 中的按鍵會被拒絕——請不要發明額外的按鍵。
- 葉節點不能有子節點:只有
Stack和Card可以接受子節點。將子節點附加到葉節點上會在匯入時被拒絕。
從組合到檢視
- 使用
syokan catalog檢查可用的類型及其屬性定義(請參閱「目錄」)。 - 將你想要顯示的資料對應到這些組件上。最上層通常是一個容器(
Stack等),垂直堆疊各個項目。 - 將其轉換為信封 JSON(請參閱「信封形狀」)。僅
root為必填。 - 使用 CLI 發布(請參閱「發布」)。成功時會印出視圖 URL。
如果你之前建立過類似的視圖,請不要從頭開始——請根據已儲存的模板來建立(請參閱「用模板實現可重複性」)。
信封形狀
POST body 中只能包含以下內容。
絕對不要包含 id、createdAt 或 url——這些由伺服器指派。
{
"root": { "type": "Stack", "props": {}, "children": [ /* 目錄節點;完整範例請參閱 references/examples.md */ ] }, // 必填。視圖樹
"title": "今天的 RSS", // 選填。顯示在清單和視圖標題中
"metadata": { "source": { "label": "daily-rss" } }, // 選填。來源標籤
"schemaVersion": 1, // 選填。伺服器會自動填入
"idempotencyKey": "rss-2026-06-28" // 選填。為此視圖命名,以便之後可以重新整理而非重複建立
}
metadata.source 除了 label 之外還可以包含其他按鍵;你可以加入 url 或 fetchedAt(例如 { "label": "gh-review", "url": "https://example.com/..." })。
對於每日或重複性的視圖,請在 idempotencyKey 中加入日期等資訊。syokan CLI 會處理其餘部分:它會先針對該按鍵進行操作,只有在沒有對應視圖時才建立新視圖——因此第一次發布會建立視圖,之後每次使用相同按鍵發布都會在原地重新整理該視圖,而不會重複建立。你不需要自行追蹤是否為第一次發布。(如果你直接使用 HTTP API 而非 CLI:POST /api/snapshots 總是建立並標記按鍵;PUT /api/snapshots 則針對現有按鍵操作,如果不存在則回傳 404——沒有「不存在時建立」的端點,因此 CLI 會先嘗試 PUT,若收到 404 則改為 POST。)
目錄
請從 syokan catalog 取得可用的 type 及其屬性定義(切勿將其抄錄到 md 中——每次使用時都從這裡取得)。
輸出為 { "items": [{ "type", "props", "childrenTypes" }] }。
props:該類型的屬性,以 JSON Schema 表示。請嚴格滿足required/enum/format(httpUrl 為uri,Time.datetime為date-time)/additionalProperties:false(未知按鍵會被拒絕)的要求。childrenTypes:null表示該容器可以接受子節點,[]表示該葉節點不接受子節點,[..]表示只允許列表中指定的類型作為子節點。
完整的組件組合範例請參閱 references/examples.md。
發布
將組裝好的信封以檔案或標準輸入傳入;成功時視圖 URL 會印到標準輸出(syokan snapshot.json / cat snapshot.json | syokan / claude -p '…JSON…' | syokan)。
至於其他所有資訊——命令、子命令、環境變數、退出碼——請查閱 syokan --help --json;類型與屬性則請查閱 syokan catalog。
預覽本地檔案
對於本地檔案,syokan <path> 是最快的方式——你直接「syokan」該檔案本身。信封 JSON 會原樣發布;其他任何內容(markdown / log / txt / json……)都會自動包裝成一個即時的 FileDoc。CLI 會將其解析為絕對路徑並交給伺服器,伺服器會讀取內容並根據副檔名推斷格式(.md/.markdown → markdown,.json → 程式碼,其他 → 純文字)。當視圖開啟時,它會即時追蹤檔案的編輯(無需重新發布)。
syokan notes.md # 渲染 markdown;每次儲存時視圖都會重新整理
syokan app.log # 以等寬字體顯示持續增長的日誌
若要將多個檔案合併到同一個視圖中,或將它們與 Heading 等其他節點混合使用,請自行放置 FileDoc 節點(屬性:path,僅接受絕對路徑;FileDoc 負責讀取和變更追蹤)。
反之,若要靜態凍結顯示檔案的內容(不需要後續更新,或者你正在轉換內容),請將內容放入 MarkdownDoc / PlainText / Code 節點中。使用 jq --rawfile 可以將內容串流傳入,無需擔心 JSON 跳脫問題。
jq -n --rawfile body README.md \
'{title:"README.md", root:{type:"Stack",props:{},children:[{type:"MarkdownDoc",props:{body:$body}}]}}' \
| syokan
用模板實現可重複性
不要每次都從頭重建一個常用的視圖——請將它儲存為 syokan 中的模板並重複使用。
模板就是「已儲存的信封本身」。你可以在骨架中放置 {{...}} 之類的標記,然後自行填入。
如果已有相符的模板,請勿從零開始建立:找到 ID → 擷取模板 → 換入資料 → 發布。當你產生一個值得保留的新視圖時,請儲存它,以便下次重現。關於子命令語法(templates list|add|get|rm),請查閱 syokan --help --json。