Communitygithub.com

wwwyo/syokan

syokan — LLM 召喚豐富的 UI。唸出一段 JSON 咒語,一個活生生的介面便隨之出現。本質上為暫時性設計。

syokan 是什麼?

syokan(日語「召喚」之意)是一個以 LLM 為核心的 UI 渲染工具。它讓大型語言模型能夠「召喚」出結構化的使用者介面:使用者只需提供一個 JSON 信封(envelope),描述由目錄組件(Catalog Components)構成的樹狀結構,syokan 就會使用預定義的組件將其渲染為可互動的視圖。 syokan 的主要價值在於它為 LLM 提供了一種純 JSON 驅動的方式來動態產生 UI,無需編寫 JSX 或前端程式碼。它支援多種平台,包括 CLI 和 HTTP API,並提供快照(snapshots)的臨時性儲存與模板重複使用機制。 syokan 的核心理念是「暫時性」:建立的視圖沒有持久性保證,僅適合存放可重建的暫時資料;但模板(templates)會被永久保存,讓使用者能重複使用常用的佈局。使用者可以透過 `syokan catalog` 指令存取目前可用的組件類型及其屬性定義,並使用 `syokan snapshot.json` 或 `cat snapshot.json | syokan` 等方式提交信封 JSON。 syokan 也支援預覽本地檔案(如 `.md`、`.log`),並且能即時追蹤檔案變更。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add wwwyo/syokan

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 可以接受子節點。將子節點附加到葉節點上會在匯入時被拒絕。

從組合到檢視

  1. 使用 syokan catalog 檢查可用的類型及其屬性定義(請參閱「目錄」)。
  2. 將你想要顯示的資料對應到這些組件上。最上層通常是一個容器(Stack 等),垂直堆疊各個項目。
  3. 將其轉換為信封 JSON(請參閱「信封形狀」)。僅 root 為必填。
  4. 使用 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。

相關技能