Communitygithub.com

wwwyo/syokan

syokan — LLMs 召唤丰富 UI。念出 JSON 咒语,一个生动的界面便应召而来。本质上是临时性的。

syokan 是什么?

syokan(召喚,意为“召唤”)是一个面向 LLM 的声明式 UI 层。核心思想是:当用户说“syokan X”,就相当于请求将数据召唤为一个视图。syokan 不依赖 JSX,而是通过一个 JSON 结构(目录组件树)来定义界面,由服务器端解析并渲染。该技能适用于 Claude Code、Cursor 等支持 CLI 工具的 AI 代理场景。开发者只需要构造符合 envelope 格式的 JSON,通过 CLI 命令 (syokan snapshot.json) 提交即可获得一个临时视图 URL。syokan 强调“快照是临时性的”,不保证持久化存储,因此适合展示可重建的瞬时数据(如当天 RSS、进行中的审查)。同时,如果需要复用相同的布局结构,可以保存模板(templates),避免每次都从头构建整个 JSON 结构。syokan 的 CLI 支持文件预览:直接 syokan <path> 即可渲染本地文件(跟随编辑实时更新);对于非 JSON 文件,会自动包装成 FileDoc 节点。复杂视图则需手动构造 envelope JSON,使用 Stick、Card 等容器组件组合 Markdown、代码、纯文本等叶子节点。整个系统严格遵循 schema:未知的 props 会被拒绝,叶子节点不允许包含子节点。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 接受子节点。将子节点附加到叶子节点上会在接收时被拒绝。

从组合到查看

  1. 通过 syokan catalog 检查可用的类型及其 props 定义(见下方 "目录")。
  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——没有 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。

相关技能