syokan은(는) 무엇을 하나요?
syokan(召喚, "소환")은 동사입니다 — LLM이 풍부한 UI를 소환합니다. 사용자가 "syokan X"(일본어: 「X를 syokan」)라고 말하면, 해당 데이터를 뷰로 소환하라는 요청입니다. 내부적으로는 스키마 기반 뷰 레이어로, JSX를 작성하는 대신 JSON 주문(카탈로그 컴포넌트의 트리)을 말하면 syokan이 미리 정의된 컴포넌트로 렌더링합니다. 당신의 작업은 데이터를 엔벨로프로 조립하여 syokan에 POST하는 것입니다. 산문에서 syokan은 타동사로 사용하십시오("do syokan" / 「syokan する」는 절대 사용하지 않음 — syokan은 그 자체로 동사입니다).
syokan이 아직 설치되지 않았거나(syokan --help 실패), 사용자가 "onboarding", "set it up", "처음 사용"이라고 말하면 references/onboarding.md를 따라 첫 번째 스냅샷까지 안내하십시오. 환경을 변경하는 작업(예: 설치)은 자동으로 실행하지 말고, 설치되지 않았다고 보고한 후 사용자의 승인을 받은 후에만 실행하십시오(절대 자체적으로 설치하지 마십시오).
필수 사항
- 스냅샷은 일시적(ephemeral)입니다: 게시된 스냅샷은 지속성이 보장되지 않습니다. 재구성 가능하고 일시적인 데이터(오늘의 RSS, 진행 중인 리뷰 등)만 넣으십시오. 재사용하는 레이아웃의 경우 템플릿을 저장하여 재현하십시오(템플릿은 지속됩니다 — 아래 "재현성을 위한 템플릿" 참조).
- JSON만 허용: 서버는 JSON 엔벨로프만 수락합니다. 원시 마크다운이나 일반 텍스트는 거부됩니다. 산문을 표시하려면
MarkdownDoc또는PlainText노드로 감싸십시오. - 엄격한 스키마: props는 엄격하게 검증됩니다. 스키마에 없는 키는 거부됩니다 — 추가 키를 임의로 생성하지 마십시오.
- 리프(leaf) 노드는 자식을 가질 수 없음:
Stack과Card만 자식을 허용합니다. 리프 노드에 자식을 첨부하면 수집 시 거부됩니다.
구성부터 보기까지
syokan catalog로 사용 가능한 타입과 props를 확인하십시오(아래 "카탈로그" 참조).- 표시하려는 데이터를 해당 컴포넌트에 매핑하십시오. 최상위 레벨은 일반적으로 컨테이너(
Stack등)로, 항목을 세로로 쌓습니다. - 엔벨로프 JSON으로 변환하십시오(아래 "엔벨로프 형태" 참조).
root만 필수입니다. - CLI로 게시하십시오(아래 "게시" 참조). 성공하면 뷰 URL이 출력됩니다.
이전에 유사한 뷰를 구축한 적이 있다면 처음부터 시작하지 말고 저장된 템플릿을 기반으로 하십시오(아래 "재현성을 위한 템플릿" 참조).
엔벨로프 형태
POST 본문에는 다음만 포함될 수 있습니다.
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가 나머지를 처리합니다: 먼저 해당 키를 대상으로 하고, 기존 뷰가 없을 때만 새 뷰를 생성합니다. 따라서 첫 번째 게시는 뷰를 생성하고, 동일한 키로 이후 게시할 때마다 중복 없이 동일한 뷰를 제자리에서 새로고침합니다. 첫 번째 게시인지 직접 추적할 필요가 없습니다. (CLI 대신 HTTP API를 직접 호출하는 경우: POST /api/snapshots는 항상 생성하고 키를 태깅합니다. PUT /api/snapshots는 기존 키를 대상으로 하며, 키가 없으면 404를 반환합니다 — 존재하지 않으면 생성하는 엔드포인트는 없으므로, CLI는 먼저 PUT을 시도하고 404에서 POST로 폴백합니다.)
카탈로그
사용 가능한 type과 해당 props 정의는 syokan catalog에서 가져오십시오 (md로 옮겨 적지 말고 — 매번 여기서 가져오십시오).
출력은 { "items": [{ "type", "props", "childrenTypes" }] }입니다.
props: JSON 스키마로 된 타입의 props입니다.required/enum/format(httpUrl은uri,Time.datetime은date-time) /additionalProperties:false(알 수 없는 키는 거부)를 정확히 충족하십시오.childrenTypes:null은 자식을 허용하는 컨테이너,[]는 자식을 허용하지 않는 리프,[..]는 나열된 타입만 자식이 될 수 있음을 의미합니다.
컴포넌트를 결합한 완전한 예제는 references/examples.md를 참조하십시오.
게시
조립된 엔벨로프를 파일 또는 stdin으로 전달하십시오. 성공하면 뷰 URL이 stdout에 출력됩니다(syokan snapshot.json / cat snapshot.json | syokan / claude -p '…JSON…' | syokan).
그 외 모든 것 — 명령어, 하위 명령어, 환경 변수, 종료 코드 — 은 syokan --help --json을 참조하십시오. 타입과 props는 syokan catalog를 참조하십시오.
로컬 파일 미리보기
로컬 파일의 경우 syokan <path>가 가장 짧은 경로입니다 — 파일 자체를 syokan합니다. 엔벨로프 JSON은 그대로 게시되며, 그 외(마크다운 / 로그 / txt / json 등)는 라이브 FileDoc에 자동으로 래핑됩니다. CLI는 이를 절대 경로로 변환하여 서버에 전달하며, 서버는 내용을 읽고 확장자에서 형식을 추론합니다(.md/.markdown → 마크다운, .json → 코드, 나머지 → 텍스트). 뷰가 열려 있는 동안 파일 수정을 추적합니다 (재게시 불필요).
syokan notes.md # 마크다운 렌더링; 저장할 때마다 뷰 새로고침
syokan app.log # 모노스페이스로 증가하는 로그 표시
여러 파일을 하나의 뷰로 결합하거나 Heading 및 다른 노드와 혼합하려면 직접 FileDoc 노드를 배치하십시오(props: 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을 참조하십시오.