Artifact format (V32)

Plain 的产物不是 PPT、Word 或 Excel 文件,而是一份 living artifact:同一份结构化的源, 能渲染成 deck(演示)、doc(长文报告)或 dashboard(数据面板)。这份源就是本页规范的 Document。

内容不该从”选 PPT / Doc / Sheet”开始。你维护一份 Document,Plain 用模板把它渲染成合适的表达 —— 换模板 0 重新生成。这是 Plain 与”单一格式”办公软件的根本区别。

顶层:Document

{
  "meta": { "title": "Q3 增长复盘", "defaultMode": "present", "density": "high" },
  "blocks": [ /* Block[] */ ]
}

字段	类型	说明
`meta`	DocMeta	文档元信息(见下)
`blocks`	Block[]	有序的语义块数组。顺序即阅读/演示顺序。

DocMeta

字段	类型	说明
`title`	string	必填。文档标题。
`defaultMode`	`"report"` \| `"present"`	默认渲染模式。`present`=分屏演示(deck),`report`=可滚动长文(doc/dashboard)。缺省 `report`。
`density`	`"low"` \| `"high"`	内容密度提示给模板。缺省 `high`。
`author` `date` `description` `deck`	string	可选。`deck` 是副标题 / 一句话引子。

defaultMode 是唯一区分”三件套”的地方,而且它只是渲染倾向。 任何 Document 都能切另一个 mode —— present 与 report 共用同一份 blocks,只是包裹层的 CSS 不同(present 按 pageBreak 切屏)。

Block 信封(所有块共有)

每个 block 都带这些字段:

字段	类型	说明
`id`	string	必填,稳定,唯一。 patch 编辑按 id 定位(不用数组下标,防插删漂移)。生成时用确定性 id。
`type`	string	块类型(见下 16 种),决定其余字段形状。
`pageBreak`	boolean?	present mode 下此块起新一屏(report mode 忽略)。
`span`	`"full"` \| `"half"` \| `"third"`?	容器 / group 内列宽。
`emphasis`	`"hero"` \| `"normal"` \| `"quiet"`?	强度提示给模板。

16 种通用 Block

type	用途	关键字段
`cover`	封面 / 大标题	`display` (主标), `kicker`, `lead`, `byline[]`
`statement`	一句核心论断 / 大数字	`text`, `bigNumber?`, `annotation?`
`prose`	Markdown 正文(收编段落/列表/洞察)	`body` (markdown), `tone?`
`heading`	分节标题	`level` (1-4), `text`
`quote`	引用	`text`, `attribution?`
`callout`	高亮框	`tone` (info/ok/warn/danger/tip/note), `body`, `title?`
`metrics`	量化指标组(收编 stats/kpi/data-block)	`items: Mark[]`, `title?`
`cards`	卡片组(收编 steps/features/diagnosis)	`layout` (grid/steps/numbered), `items: CardItem[]`
`sequence`	序列(时间轴 / 流程)	`flow` (time/arrow), `items: SeqItem[]`
`compare`	左右对比	`left: Col`, `right: Col`
`quadrant`	二维定位图	`xLabel`, `yLabel`, `quadrantLabels[4]`, `points[]`
`table`	表格	`headers[]`, `rows[][]`
`chart`	图表	`variant` (line/bar/area/bar-stack/pie/scatter), `x[]`, `series[]`
`media`	图文 / 引用 / 图表 + 文字分栏	`text{title,...}`, `media{kind,src?}`, `side` (left/right)
`closing`	结尾 / CTA	`display`, `cta{primary?,secondary?}`
`group`	递归容器(把多块排成 row / stack)	`layout` (row/stack), `children: Block[]`

复用的原子结构

Mark      = { value, label, hint?, delta?: "up"|"down"|"flat" }
CardItem  = { head, body, num?, icon?, when?, metric?, metricLabel? }
SeqItem   = { label, when?, hint? }
Col       = { label, bullets: string[] }
ChartSeries = { name, data: number[] }

三条不变量

Ids are identity

block 的 id 是它的身份。编辑(patch)靠 id 定位,不靠数组下标。生成时发确定性 id, 编辑时永不重新生成已有 block 的 id(会让引用/版本对不上)。

Pure data

Document 是纯数据,永不携带可执行代码。chart 的配置是纯 JSON(无函数); prose 的 markdown 与文本会被 sanitize。AI 只输出这份 content JSON,不写 HTML —— 模板负责渲染。

Additive & forward-compatible

格式增量演进。生成时只用本页列出的字段;不要发明属性名(未知键会被丢弃,typo 导致样式丢失)。

给 agent 的约定

Plain 通过 MCP(plain mcp → generate_artifact / edit_artifact)和 CLI(plain generate --as deck|doc|sheet) 暴露生成与编辑。agent 不直接拼 Document JSON —— 给意图,Plain 生成合规的 Document; 要改就发自然语言指令或 block.id 定位的 JSON Patch。

数值对比 → chart 或 metrics(比散落的文本框强)
结构化网格 → table
步骤 / 时间线 → sequence 或 cards[layout=steps]
需要并排 → group[layout=row] 包多块
编辑已有产物 → 保留原 block 的 id,只改字段

Don’t

不发明本页未列的属性名(未知键静默丢弃)
不在 content 里写 HTML / 内联样式 / 可执行代码(交给模板)
不为已有 block 重新生成 id
不假设某个 type 支持未列出的字段

与渲染的关系

一份 Document → 模板(token + 每种 block 的 renderer)→ 自包含 HTML。

report mode:blocks 垂直流,可滚动(doc / dashboard 默认)
present mode:按 pageBreak 切屏,每屏是一页(deck 默认)

同一份 Document 换任意模板、切任意 mode,都不需要重新调用 AI。这就是”一份源,多种活的 Artifact”。

Welcome

Three forms

Workflow

Brand templates

AI agents

Artifact format (V32)

顶层:Document

DocMeta

Block 信封(所有块共有)

16 种通用 Block

复用的原子结构

三条不变量

Ids are identity

Pure data

Additive & forward-compatible

给 agent 的约定

与渲染的关系

​顶层:Document

​DocMeta

​Block 信封(所有块共有)

​16 种通用 Block

​复用的原子结构

​三条不变量

Ids are identity

Pure data

Additive & forward-compatible

​给 agent 的约定

​与渲染的关系

顶层:Document

DocMeta

Block 信封(所有块共有)

16 种通用 Block

复用的原子结构

三条不变量

给 agent 的约定

与渲染的关系