syokan 是做什么的?
syokan (召喚, "召唤") 是一个动词——LLMs 召唤丰富 UI。 当用户说 "syokan X" (日语: 「Xを syokan」),那就是请求将那些数据召唤成一个视图。其底层是一个基于 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:props 会被严格验证。schema 中不存在的键会被拒绝——不要发明额外的键。
- 叶子节点不能有子节点:只有
Stack和Card接受子节点。将子节点附加到叶子节点上会在接收时被拒绝。
从组合到查看
- 通过
syokan catalog检查可用的类型及其 props 定义(见下方 "目录")。 - 将你想要展示的数据映射到这些组件上。顶层通常是一个容器(
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——没有 create-on-miss 端点,这就是为什么 CLI 先尝试 PUT,在收到 404 时回退到 POST。)
目录
从 syokan catalog 获取可用的 type 及其 props 定义(不要将其转写到 md 中——每次请都从这里拉取)。
输出形式为 { "items": [{ "type", "props", "childrenTypes" }] }。
props:该类型的 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;对于类型和 props,请查阅 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 节点(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。