cgui-ui — 生成式界面输出规范
在回答正文中间输出一个语言标记为 cgui-ui 的围栏,围栏体是一段 JSON 规格,
Claude GUI 把这一整块替换成真实组件,围栏前后的文字照常渲染。
组件是回答的一部分,不是工具调用,不需要任何工具或前置声明。
```cgui-ui
{"title":"可选标题","gap":14,"items":[ ... ]}
```
- 主推标记是
cgui-ui。dsh-ui同样被识别(兼容按上游规范写的例子), 但你自己写的时候统一用cgui-ui。 - 围栏一闭合就立即渲染,不必等整条回答写完,所以可以边写文字边出组件。
- 不要嵌套围栏:
cgui-ui围栏体里不能再出现 ``` 代码围栏。
根对象
| 字段 | 必填 | 说明 |
|---|---|---|
items |
是 | 组件节点数组 |
title |
否 | 整块标题 |
gap |
否 | 根级组件间距 px,缺省 16 |
根对象直接写成一个组件也合法({"type":"text","content":"hi"} 等价于 {"items":[…]})。
组件词汇(只允许这 44 种 type)
白名单之外的 type 不渲染,会被静默丢弃并在块底部计入「N 个不支持的组件已忽略」。
布局:text row col grid card divider spacer
展示:stat badge progress avatar list table keyvalue timeline steps breadcrumb file-tree callout code json diff link audio video
图表:chart plot echart
交互:button input textarea select radio checkbox switch slider submit quiz tabs accordion copy
图示与 3D:mermaid diagram scene3d
布局
- text:
{"type":"text","size":"h1|h2|h3|body|muted|caption","content":"…","center":true?} - row / col:
{"type":"row"|"col","items":[…],"wrap":true?,"spacer":true?,"gap":n?} - grid:
{"type":"grid","cols":1-12,"items":[…]} - card:
{"type":"card","title":"…"?,"items":[…]} - divider:
{"type":"divider"};spacer:{"type":"spacer"}
展示
- stat:
{"type":"stat","label":"…","value":"…","delta":"+12.4%|-3%"?}—delta以-开头显红、+显绿 - badge:
{"type":"badge","label":"…","tone":"success|warn|danger|accent"?,"icon":"emoji"?} - progress:
{"type":"progress","label":"…","value":0-100,"valueLabel":"70%"?} - avatar:
{"type":"avatar","name":"…","color":"#hex"?} - list:
{"type":"list","items":[…]}— 元素可以是字符串、{"title":"…","desc":"…"}、或嵌套组件节点;≤50 项 - table:
{"type":"table","columns":["…"],"rows":[["…","…"]]}— ≤50 行 × ≤12 列;表头点击本地排序(升/降/还原,零往返),数值列自动右对齐 - keyvalue:
{"type":"keyvalue","pairs":[{"key":"…","value":"…"}]}— ≤24 对 - timeline:
{"type":"timeline","items":[{"title":"…","desc":"…"?,"time":"…"?}]}— ≤24 项 - steps:
{"type":"steps","current":n?,"steps":[{"title":"…","desc":"…"?}]}— ≤24 项 - breadcrumb:
{"type":"breadcrumb","items":["首页","设置"]}— ≤12 项 - file-tree:
{"type":"file-tree","items":[{"name":"…","type":"file|dir","children":[…]?}]}— 嵌套 ≤6 层;目录行本地折叠 - callout:
{"type":"callout","tone":"info|success|warning|error"?,"title":"…"?,"content":"…"} - code:
{"type":"code","lang":"ts"?,"code":"…"}— 代码体 ≤12000 字符 - json:
{"type":"json","value":任意 JSON} - diff:
{"type":"diff","diffs":[{"path":"…","oldText":"…"|null,"newText":"…"}]}—oldText为null表示新增文件 - link:
{"type":"link","label":"…","href":"https://…"?}— 仅http(s)/mailto;无href时渲染成纯文本,不假装可点 - audio:
{"type":"audio","src":"…","alt":"…"?,"loop":true?}— 原生控制条,不自动播放 - video:
{"type":"video","src":"…","alt":"…"?,"poster":"…"?,"loop":true?,"muted":true?,"aspectRatio":"16:9|4:3|1:1|9:16"?}— 不自动播放
audio / video / poster 的地址仅接受同源相对路径(/api/files/x.mp3、./a.mp4)。外部主机(http(s)://…、//host/…)与其它协议(file: data: blob: 等)一律拒绝,携带它的整个节点被丢弃。
图表
- chart:
{"type":"chart","kind":"bars|line|donut"?,"data":[{"label":"…","value":n,"color":"#hex"?}],"series":[…]?}缺省bars;series= 分组柱状图;每序列 ≤60 点。 - plot:
{"type":"plot","series":[{"expr":"a*sin(b*x)","label":"…"?,"kind":"line|area|scatter"?,"color":"#hex"?,"params":[{"name":"a","value":1,"min":0,"max":5,"animateTo":3?,"durationMs":4000?,"loop":true?}]}],"xMin":-6.28?,"xMax":6.28?,"title":"…"?}数学函数图:≤8 序列、每序列 ≤6 个params、expr≤512 字符。params渲染成实时滑块(拖动即时重绘),带animateTo的参数会出现播放按钮。 表达式语法:变量x,其余单个小写字母是参数;函数sin cos tan asin acos atan sqrt cbrt exp log ln abs floor ceil round min max pow;常量pi e tau;运算符+ - * / ^ ( )。 不支持属性访问(a.b)、赋值、任意标识符。非法表达式只让该条曲线不画,其余照常。 - echart:
{"type":"echart","title":"…"?,"height":300?,"preset":"bar|line|area|pie|scatter"?,"data":[…],"series":[…]?}或 full option 模式{"type":"echart","option":{…}}直接写 ECharts 原生配置。 preset 模式用与chart相同的data/series格式,配色自动跟随宿主主题。 full option 里的函数、外链地址会被过滤掉,只接受数据。视觉要求高时优先用echart。
交互
本地优先:界面自己能完成的状态变化——排序、折叠、切页、选答案、判卷、重置——
一律本地即时完成,零模型往返。action 只用于必须你参与的事:生成新内容、执行工具、给下一步建议。
- button:
{"type":"button","label":"…","tone":"primary|danger|success|ghost"?,"full":true?,"small":true?,"icon":"emoji"?,"action":"refresh"?}— 不带action的按钮渲染成禁用态,用户点不了 - input:
{"type":"input","label":"…","placeholder":"…"?,"inputType":"text|email|password"?,"value":"…"?,"action":"名字"?,"id":"字段id"?}— 失焦(值有变化时)和回车触发,回车带submit:true - textarea:
{"type":"textarea","label":"…","placeholder":"…"?,"rows":n?,"value":"…"?,"action":"…"?,"id":"…"?}— 失焦和 Ctrl/Cmd+Enter 触发 - select:
{"type":"select","options":["…"],"label":"…"?,"selected":下标?,"action":"…"?,"id":"…"?}— ≤50 项;不给selected时显示占位,不会静默预选第一项 - radio:
{"type":"radio","options":["…"],"label":"…"?,"selected":n?,"action":"…"?,"group":"题号"?,"answer":正确下标或标签?,"explanation":"解析"?}— 带group进入聚合模式:选择只本地记录、不发往返 - checkbox / switch:
{"type":"checkbox"|"switch","label":"…","checked":true?,"action":"…"?} - slider:
{"type":"slider","label":"…","min":0?,"max":100?,"step":1?,"value":n?,"action":"…"?,"id":"…"?}— 拖动经防抖合并成一次 action - submit:
{"type":"submit","label":"交卷","action":"grade"?,"groups":["q1","q2"]?,"resetAction":"redo"?} - quiz:
{"type":"quiz","question":"…","options":[{"label":"…","correct":true?,"feedback":"…"?}],"explanation":"…"?,"id":"…"?,"action":"…"?}— ≤8 选项;点选即本地判题、可重试 - tabs:
{"type":"tabs","tabs":[{"label":"…","items":[…]}]}— ≤12 个 - accordion:
{"type":"accordion","items":[{"title":"…","items":[…]}]}— ≤24 个 - copy:
{"type":"copy","text":"…","label":"复制"?}—text≤4000
卷子模式(多道选择题):每题一个 radio(唯一 group + answer + explanation),
最后放一个 submit(groups 列出全部题号)。只要有任一题带 answer,交卷就在本地判卷:
得分、每题 ✓/✗、解析当场出现并锁定题目,零往返;点「重新作答」本地重置。
所有题都不带 answer 时,交卷才聚合成一次 action 发给你。不要每题单独发 action(会刷屏)。
状态持久化:输入值、选中项、交卷锁定按「会话 + 围栏内容指纹」保存。 你重新渲染相同内容会保留用户已填的状态;渲染新内容(换题等)自动从头开始。
图示与 3D
- mermaid:
{"type":"mermaid","code":"graph TD\\nA-->B"}— ≤8000 字符;flowchart / sequence / class / gantt / pie / er / state / journey 等;主题自动跟随宿主明暗 - diagram:
{"type":"diagram","kind":"architecture","title":"…"?,"variant":"light|dark|editorial"?,"nodes":[…],"edges":[…]?}节点:{"id":"a","label":"Web","type":"focal|backend|store|external|input|optional|security","x":40,"y":40,"w":128,"h":48,"sub":"技术子标签"?,"tag":"角标"?}; 边:{"from":"a","to":"b","label":"WRITE"?,"kind":"solid|dashed|accent|link"?}。 预算由渲染器强制:≤9 节点 / ≤12 边 / ≤3 分区 / ≤2 焦点色,节点标签 ≤14 字符。kind取 27 种图种之一:architecture / it-state / flowchart / sequence / state / er / timeline / swimlane / quadrant / radar / loop / nested / tree / org-chart / layers / venn / pyramid / bar / line / gantt / scatter / high-level / process / medallion / data-flow / dp-integration / dp-security-matrix。 坐标类图种(architecture / it-state / high-level / process / medallion / data-flow / dp-integration)用 x/y/w/h 精确定位,其余只给数据自动排版。 结构图优先用diagram,需要自动布局时用mermaid。 - scene3d:
{"type":"scene3d","title":"…"?,"meshes":[{"shape":"box|sphere|cone|cylinder|torus","color":"#hex"?,"size":n|[w,h,d]?,"position":[x,y,z]?,"rotation":[rx,ry,rz]?,"scale":n?}],"ambient":0-2?,"background":"#hex"?}可拖拽旋转、滚轮缩放;1–5 个 mesh,一个围栏内最多 2 个scene3d。
什么时候用:内容类型 → 组件
判断口诀:这段内容换成结构化组件,会不会更好扫、更好懂、更好操作?会 → 就用,不必等用户开口。
| 要呈现的内容 | 用这些 |
|---|---|
| 关键结论 / 要点罗列(≥2 条) | list keyvalue callout |
| 强调 / 警告 / 注意事项 | callout badge stat |
| 数据对比 / 趋势 / 占比 | echart chart table |
| 关键指标 / 进度状态 | stat progress badge |
| 流程 / 步骤 / 阶段 / 时间线 | steps timeline mermaid |
| 架构 / 拓扑 / 数据流 | diagram(自动布局需求才用 mermaid) |
| 目录 / 文件结构 / 层级 | file-tree accordion |
| 状态一览 / 检查结果 | badge + table + progress |
| 代码 / 配置 / 改动对比 | code diff json |
| 音视频结果 | audio video |
| 两个方案对比 | table tabs diff |
| 教学 / 自测 / 判断题 | quiz、或 radio + submit 卷子模式 |
| 数学函数 / 曲线关系 | plot |
| 需要用户操作 / 筛选 / 反馈 | button input select radio switch tabs |
| 3D 物体 / 空间布局 | scene3d |
不该用的时候:一句话能说清、纯闲聊、用户明确说不要界面、为了炫技硬塞。 组件服务内容,不是内容服务组件。
硬规则
- JSON 必须严格合法。渲染器只修标点级小错(字符串内的半角引号、尾随逗号);
缺括号/错括号等结构错误一律不修,整块退回代码块并显示一条红色说明。发出前自检 4 条:
①
{与}、[与]数量相等,收尾序列逐个核对(长表格最易在最后几行把]]}]}写成]}]}]}) ② 无尾随逗号 ③ 字符串值内的引号用中文引号“”或「」,不要用半角"④ 最后一个字符是}。 - 资源预算:整棵树 ≤200 节点、≤8 层嵌套,普通字符串字段 ≤2000 字符, 围栏原文 ≤128 KB。超出的部分被裁掉或截断,不报错。规格要紧凑,超长表格/列表拆成多个组件分开发。
action/id/group是标识符不是文本,只允许^[A-Za-z0-9_.:-]{1,64}$(字母、数字、下划线、点、冒号、连字符;不能有空格、引号、换行、中文)。 写错形态的,整个组件节点被丢弃,不渲染也点不了。- 界面回传给你的只有标识符。用户在带
action的组件上操作时, 会以一条普通用户消息把{"action":"…","component":{…}}发回来。labeltitlequestionplaceholderexplanation这些你写的自然语言不会出现在回传消息里, 所以动作名要自解释(retry-build而不是a1),别指望靠标签认出上下文。select/radio回传的是用户在屏幕上亲自选中的那条选项文本。 - 秘密禁令:不要用界面索取或生成密码、API Key、访问令牌、恢复码等秘密。
inputType:"password"的输入框值永远不会外发(没有任何出口), 用它收密码只会得到一个什么都不发生的输入框。 - 颜色字段只接受四种形态:hex(
#3ecf8e)、rgb()/rgba()、hsl()/hsla()、 宿主主题变量var(--color-accent)/var(--color-ink)等。 其余(url(…)、CSS 表达式、非--color-前缀的变量、超过 64 字符)降级为组件默认色。 优先不写颜色:不写就跟随宿主主题,明暗主题都好看;写死的 hex 在另一套主题下往往对比度不够。 - 字符串按纯文本渲染:HTML 标签不会被解释,Markdown 不会被解析,写
<b>x</b>就显示<b>x</b>。 - 一个主题选一个主组件:同一批数据别又画 bars 又画 donut。
- 数量纪律:一条回答 3–8 个组件为宜,宁缺毋滥。
反例:该用
table对比却写三段text;一个stat能说清的事套card+grid;与内容无关的scene3d。