飞书画板lark-whiteboard里程碑时间线图 DSL 绘制指南从布局规则到骨架模板实战【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址: https://gitcode.com/gh_mirrors/cli414/cli导读里程碑时间线Milestone Timeline是产品版本演进、项目排期、公司大事记等场景中最常用的可视化形式之一。在飞书 CLI 的 lark-whiteboard 技能中这一场景由 scenes/milestone.md 场景指南定义了一套完整的 DSL 绘制规范包括节点数量约束、两种布局选型、箭头形年份条 虚线卡片的视觉结构以及可直接套用的 JSON 骨架模板。读完本文你将掌握如何在飞书画板中通过layout: none绝对定位 connector 时间轴的方式从零构建一张专业、严格对齐的里程碑时间线图并了解如何结合 whiteboard-cli 与lark-cli whiteboard update将其写入真实画板。一、里程碑时间线场景定位与核心约束在 routes/dsl.md 的场景指南索引中里程碑scenes/milestone.md被明确标注为适用于「时间线、版本演进」类图表与架构图、泳道图、鱼骨图等并列是 DSL 路径下的一种标准场景范式。该场景的Content 约束内容约束非常明确节点数量 4-8 个里程碑数量有严格上下限太少撑不起时间线的叙事太多则容易拥挤下文「陷阱」一节会专门说明超限处理每个节点由三部分组成标题 日期 可选描述时间语义从左到右递增节点在画布上的水平位置x 坐标承载时间先后关系越靠右越晚。这意味着里程碑图的信息结构是「一维序列」天然适合把 x 坐标当作时间的映射轴——这也是该场景选择绝对定位而非 Flex/Dagre 的根本原因对应 elements/layout.md 中「节点位置本身有含义拓扑图、地图、时间线轴时用绝对定位」的布局决策原则。二、两种布局选型横向时间线 vs 交替上下原文档给出了两种按需选择的布局方案它们对应不同节点数量下的最优视觉表现方案实现方式适用场景横向时间线horizontal frame节点等分节点较少默认推荐结构规整交替上下绝对定位节点交替分布在时间轴上下方节点较多时更紧凑避免单侧堆积选型判断当节点数接近上限如 6-8 个时若全部排在一侧卡片会纵向撑得很高或横向挤得很密采用上下交替布局可以让左右相邻节点的卡片错开压缩整体纵向高度。从 elements/content.md 的分组与精简原则来看超过 5 个节点的横排已经属于「一行放不下」的范畴需要主动考虑布局策略调整。三、结构特征一张标准里程碑图由哪些元素构成原文档对里程碑图的结构特征做了精确定义这是判断渲染结果是否符合预期的视觉验收标准标题居中图表标题如「产品 2024 年度里程碑」放在画布顶部居中年份/时间轴条使用箭头形色块承载年份如 2024、2025按时间从左到右递增排列里程碑卡片时间轴下方放置虚线圆角卡片承载里程碑标题与描述严格对齐年份条与对应卡片等宽、左右对齐两者的 x 与 width 必须完全一致文字层级标题加粗在上如 fontSize 16描述文字更小更浅在下如 fontSize 13均居中对齐——这与 elements/typography.md 的「字号层级表」完全吻合H3 15-16 用于卡片标题、Caption 13 用于辅助说明且同张图不超过 3 个字号层级。箭头形年份条的实现在 DSL 中借助SVG 节点完成。按 elements/schema.md 的 SVG 渲染规范内联 SVG 必须包含viewBox与xmlns属性且只能使用纯几何绘制元素——里程碑场景使用的polygon points0,0 170,0 190,18 170,36 0,36/正是允许的图形之一通过三个点的坐标描绘出右侧带箭头的色块形状。四、Layout 规则绝对定位下的坐标纪律原文档对布局规则的描述是里程碑图能够「严格对齐」的关键逐条拆解如下绝对定位为主整个画布容器使用layout: none节点位置x/y直接承载时间序列含义先定数量再算坐标先确定里程碑数量 N再计算等距的 x 坐标序列——例如画布宽 1200、卡片宽 190 时x 依次取 50、290、530…步长 卡片宽 间距时间轴用 connector 贯穿所有节点用一条贯穿的连线把整个时间序列串起来节点与时间轴用短竖线连接每个里程碑卡片通过短的竖直连线挂到时间轴上节点间水平间距一致等距分布保证时间刻度均匀年份条宽度 卡片宽度垂直间距统一保证上下视觉对位标题与年份区域保留足够留白标题区y≈12-44与年份条y≈56之间、年份条与卡片y≈132之间留有清晰间隔。从 elements/layout.md 的绝对定位规则可以印证两点实现细节layout: none的容器必须有固定宽高骨架示例中外层 frame 显式声明了width: 1200, height: 360绝不能写成fit-content否则子节点绝对定位会错乱flex 容器内的 x/y 会被完全忽略这也解释了为什么里程碑图必须用layout: none而非 horizontal frame——x 坐标是时间轴的核心语义不能被 Flex 接管。关于时间轴连线elements/connectors.md 还给出了一个与本场景强相关的约束绘制坐标轴/数轴必须使用lineShape: straight因为polyline/rightAngle的自动避障机制可能在刻度元素触发时把线条绕弯破坏时间轴的笔直性。同时 connector 必须放在根nodes数组与顶层 frame 平级不能嵌套在children中。五、骨架示例精解可直接复用的完整 DSL以下是原文档给出的完整骨架示例双节点版实际使用时按节点数复制扩展{ version: 2, nodes: [ { type: frame, x: 0, y: 0, width: 1200, height: 360, layout: none, children: [ { type: text, x: 300, y: 12, width: 600, height: fit-content, text: [{ content: {{CHART_TITLE}}, bold: true, fontSize: 24 }], textAlign: center }, { type: svg, x: 50, y: 56, width: 190, height: 36, svg: { code: svg xmlns\http://www.w3.org/2000/svg\ viewBox\0 0 190 36\polygon points\0,0 170,0 190,18 170,36 0,36\//svg } }, { type: text, x: 50, y: 64, width: 190, height: fit-content, text: {{DATE_1}}, textAlign: center }, { type: rect, x: 50, y: 132, width: 190, height: 120, borderDash: dashed, borderRadius: 8 }, { type: text, x: 50, y: 150, width: 190, height: fit-content, text: [{ content: {{MILESTONE_1_TITLE}}, bold: true, fontSize: 16 }], textAlign: center }, { type: text, x: 50, y: 180, width: 190, height: fit-content, text: {{MILESTONE_1_DESC}}, fontSize: 13, textAlign: center }, { type: svg, x: 290, y: 56, width: 190, height: 36, svg: { code: svg xmlns\http://www.w3.org/2000/svg\ viewBox\0 0 190 36\polygon points\0,0 170,0 190,18 170,36 0,36\//svg } }, { type: text, x: 290, y: 64, width: 190, height: fit-content, text: {{DATE_2}}, textAlign: center }, { type: rect, x: 290, y: 132, width: 190, height: 120, borderDash: dashed, borderRadius: 8 }, { type: text, x: 290, y: 150, width: 190, height: fit-content, text: [{ content: {{MILESTONE_2_TITLE}}, bold: true, fontSize: 16 }], textAlign: center }, { type: text, x: 290, y: 180, width: 190, height: fit-content, text: {{MILESTONE_2_DESC}}, fontSize: 13, textAlign: center } ] } ] }对模板中的占位符与坐标规律做逐一说明便于扩展到 8 个节点占位符含义取值建议{{CHART_TITLE}}图表标题加粗、fontSize 24居中于画布顶部{{DATE_N}}第 N 个里程碑的年份/日期如 2024 Q1fontSize 13-14{{MILESTONE_N_TITLE}}第 N 个里程碑标题加粗、fontSize 16{{MILESTONE_N_DESC}}第 N 个里程碑描述可选fontSize 13更小更浅坐标递推规律对应原文档「先确定里程碑数量计算等距的 x 坐标序列」年份条与卡片统一宽度190x 步长为240190 卡片宽 50 间距即第 N 个节点的x 50 (N-1) × 240同一节点的年份条y56、日期文字y64、卡片y132、标题y150、描述y180纵向层叠垂直间距统一日期文字与箭头色块共用 x/width保证「年份条与卡片等宽、左右对齐」。需要补充的还有两个模板未展开的要素时间轴 connector在根nodes数组中追加一条lineShape: straight的连线贯穿所有节点如from: {x: 50, y: 100}, to: {x: 770, y: 100}每个节点再配一条短竖线如从{x: 145, y: 100}到{x: 145, y: 132}连接卡片连线必须放在根 nodes 数组末尾不能放进 frame 的 children见 elements/connectors.md文字高度用fit-content所有含文字节点标题、日期、卡片标题、描述的 height 均为fit-content因为引擎不支持 overflow写死高度会截断文字见 elements/layout.md 注意事项第 5 条。六、陷阱清单四个必须避开的坑原文档以「陷阱」小节收尾这些是渲染审查对应 routes/dsl.md Step 3 的检查清单时必须重点排查的点节点太多时太拥挤超过 6 个节点时应切换为交替上下布局节点交替分布在时间轴上下方或增大画布宽度画布宽度常用范围 1000-1400px见 elements/layout.md 的常用间距表右侧节点与时间轴末端重叠最后一个节点的x width不要超出画布边界——例如画布 1200 宽、卡片 190 宽时最后一个节点的 x 应满足x 190 ≤ 1200即 x 最大约 1010年份条与卡片不对齐年份条和卡片的x、width 必须完全一致——这是本场景最容易出现的视觉瑕疵根源往往是复制扩展模板时只改了 x 忘了同步 width或年份条与卡片各自采用了不同的步长连线形状误用时间轴必须用straight直线若误用polyline/rightAngle刻度附近的自动避障可能把时间轴绕出弧度由 elements/connectors.md 的坐标轴规则引申。七、端到端落地从 DSL 到真实画板骨架模板产出diagram.json后按 references/lark-whiteboard-workflow.md 的「渲染 写入画板」流程执行完整命令语法见 references/lark-whiteboard-update.mdStep 1本地渲染审查npx -y larksuite/whiteboard-cli^0.2.13 -i diagram.json -o diagram.png用 PNG 做预览验证信息是否完整、布局是否合理、文字有无截断、年份条与卡片是否对齐、时间轴是否笔直。发现问题按上述陷阱清单修复后重新渲染最多两轮。Step 2转换为 OpenAPI 格式并写入画板npx -y larksuite/whiteboard-cli^0.2.13 -i diagram.json --to openapi --format json \ | lark-cli whiteboard update --whiteboard-token board_token \ --source - --input_format raw --idempotent-token 时间戳标识 --as user关键参数说明详见 lark-whiteboard-update.md--whiteboard-token目标画板 tokenwbcnXXX格式需拥有画板编辑权限--input_format rawDSL 产物必须先用 whiteboard-cli 转成 OpenAPI 原生节点格式再以raw写入--idempotent-token幂等 token最少 10 个字符建议使用时间戳 场景标识拼接如1744800000-milestone-1同一次逻辑更新只生成一次重试时原样复用切勿每次重试都重新生成否则会重复写入--as user画板操作默认以用户身份执行参见 SKILL.md 的快速决策首次写入空白画板时无需--overwrite若写入已有内容画板并需覆盖则要附加--overwrite并确认会整板重建。结语里程碑时间线是 lark-whiteboard DSL 路径中最典型的「绝对定位承载语义」场景x 坐标即时间、layout: none容器 固定宽高是前提、箭头 SVG 虚线卡片是视觉骨架、等距步长与严格对齐是质量底线。掌握 scenes/milestone.md 的约束与骨架模板再结合 schema.md、layout.md、connectors.md 的底层规则即可稳定产出可写入飞书画板的版本演进时间线也能轻松迁移到组织大事记、项目排期等同类时间序列图表。【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址: https://gitcode.com/gh_mirrors/cli414/cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 飞书画板（lark-whiteboard）里程碑时间线图 DSL 绘制指南：从布局规则到骨架模板实战
飞书画板lark-whiteboard里程碑时间线图 DSL 绘制指南从布局规则到骨架模板实战【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址: https://gitcode.com/gh_mirrors/cli414/cli导读里程碑时间线Milestone Timeline是产品版本演进、项目排期、公司大事记等场景中最常用的可视化形式之一。在飞书 CLI 的 lark-whiteboard 技能中这一场景由 scenes/milestone.md 场景指南定义了一套完整的 DSL 绘制规范包括节点数量约束、两种布局选型、箭头形年份条 虚线卡片的视觉结构以及可直接套用的 JSON 骨架模板。读完本文你将掌握如何在飞书画板中通过layout: none绝对定位 connector 时间轴的方式从零构建一张专业、严格对齐的里程碑时间线图并了解如何结合 whiteboard-cli 与lark-cli whiteboard update将其写入真实画板。一、里程碑时间线场景定位与核心约束在 routes/dsl.md 的场景指南索引中里程碑scenes/milestone.md被明确标注为适用于「时间线、版本演进」类图表与架构图、泳道图、鱼骨图等并列是 DSL 路径下的一种标准场景范式。该场景的Content 约束内容约束非常明确节点数量 4-8 个里程碑数量有严格上下限太少撑不起时间线的叙事太多则容易拥挤下文「陷阱」一节会专门说明超限处理每个节点由三部分组成标题 日期 可选描述时间语义从左到右递增节点在画布上的水平位置x 坐标承载时间先后关系越靠右越晚。这意味着里程碑图的信息结构是「一维序列」天然适合把 x 坐标当作时间的映射轴——这也是该场景选择绝对定位而非 Flex/Dagre 的根本原因对应 elements/layout.md 中「节点位置本身有含义拓扑图、地图、时间线轴时用绝对定位」的布局决策原则。二、两种布局选型横向时间线 vs 交替上下原文档给出了两种按需选择的布局方案它们对应不同节点数量下的最优视觉表现方案实现方式适用场景横向时间线horizontal frame节点等分节点较少默认推荐结构规整交替上下绝对定位节点交替分布在时间轴上下方节点较多时更紧凑避免单侧堆积选型判断当节点数接近上限如 6-8 个时若全部排在一侧卡片会纵向撑得很高或横向挤得很密采用上下交替布局可以让左右相邻节点的卡片错开压缩整体纵向高度。从 elements/content.md 的分组与精简原则来看超过 5 个节点的横排已经属于「一行放不下」的范畴需要主动考虑布局策略调整。三、结构特征一张标准里程碑图由哪些元素构成原文档对里程碑图的结构特征做了精确定义这是判断渲染结果是否符合预期的视觉验收标准标题居中图表标题如「产品 2024 年度里程碑」放在画布顶部居中年份/时间轴条使用箭头形色块承载年份如 2024、2025按时间从左到右递增排列里程碑卡片时间轴下方放置虚线圆角卡片承载里程碑标题与描述严格对齐年份条与对应卡片等宽、左右对齐两者的 x 与 width 必须完全一致文字层级标题加粗在上如 fontSize 16描述文字更小更浅在下如 fontSize 13均居中对齐——这与 elements/typography.md 的「字号层级表」完全吻合H3 15-16 用于卡片标题、Caption 13 用于辅助说明且同张图不超过 3 个字号层级。箭头形年份条的实现在 DSL 中借助SVG 节点完成。按 elements/schema.md 的 SVG 渲染规范内联 SVG 必须包含viewBox与xmlns属性且只能使用纯几何绘制元素——里程碑场景使用的polygon points0,0 170,0 190,18 170,36 0,36/正是允许的图形之一通过三个点的坐标描绘出右侧带箭头的色块形状。四、Layout 规则绝对定位下的坐标纪律原文档对布局规则的描述是里程碑图能够「严格对齐」的关键逐条拆解如下绝对定位为主整个画布容器使用layout: none节点位置x/y直接承载时间序列含义先定数量再算坐标先确定里程碑数量 N再计算等距的 x 坐标序列——例如画布宽 1200、卡片宽 190 时x 依次取 50、290、530…步长 卡片宽 间距时间轴用 connector 贯穿所有节点用一条贯穿的连线把整个时间序列串起来节点与时间轴用短竖线连接每个里程碑卡片通过短的竖直连线挂到时间轴上节点间水平间距一致等距分布保证时间刻度均匀年份条宽度 卡片宽度垂直间距统一保证上下视觉对位标题与年份区域保留足够留白标题区y≈12-44与年份条y≈56之间、年份条与卡片y≈132之间留有清晰间隔。从 elements/layout.md 的绝对定位规则可以印证两点实现细节layout: none的容器必须有固定宽高骨架示例中外层 frame 显式声明了width: 1200, height: 360绝不能写成fit-content否则子节点绝对定位会错乱flex 容器内的 x/y 会被完全忽略这也解释了为什么里程碑图必须用layout: none而非 horizontal frame——x 坐标是时间轴的核心语义不能被 Flex 接管。关于时间轴连线elements/connectors.md 还给出了一个与本场景强相关的约束绘制坐标轴/数轴必须使用lineShape: straight因为polyline/rightAngle的自动避障机制可能在刻度元素触发时把线条绕弯破坏时间轴的笔直性。同时 connector 必须放在根nodes数组与顶层 frame 平级不能嵌套在children中。五、骨架示例精解可直接复用的完整 DSL以下是原文档给出的完整骨架示例双节点版实际使用时按节点数复制扩展{ version: 2, nodes: [ { type: frame, x: 0, y: 0, width: 1200, height: 360, layout: none, children: [ { type: text, x: 300, y: 12, width: 600, height: fit-content, text: [{ content: {{CHART_TITLE}}, bold: true, fontSize: 24 }], textAlign: center }, { type: svg, x: 50, y: 56, width: 190, height: 36, svg: { code: svg xmlns\http://www.w3.org/2000/svg\ viewBox\0 0 190 36\polygon points\0,0 170,0 190,18 170,36 0,36\//svg } }, { type: text, x: 50, y: 64, width: 190, height: fit-content, text: {{DATE_1}}, textAlign: center }, { type: rect, x: 50, y: 132, width: 190, height: 120, borderDash: dashed, borderRadius: 8 }, { type: text, x: 50, y: 150, width: 190, height: fit-content, text: [{ content: {{MILESTONE_1_TITLE}}, bold: true, fontSize: 16 }], textAlign: center }, { type: text, x: 50, y: 180, width: 190, height: fit-content, text: {{MILESTONE_1_DESC}}, fontSize: 13, textAlign: center }, { type: svg, x: 290, y: 56, width: 190, height: 36, svg: { code: svg xmlns\http://www.w3.org/2000/svg\ viewBox\0 0 190 36\polygon points\0,0 170,0 190,18 170,36 0,36\//svg } }, { type: text, x: 290, y: 64, width: 190, height: fit-content, text: {{DATE_2}}, textAlign: center }, { type: rect, x: 290, y: 132, width: 190, height: 120, borderDash: dashed, borderRadius: 8 }, { type: text, x: 290, y: 150, width: 190, height: fit-content, text: [{ content: {{MILESTONE_2_TITLE}}, bold: true, fontSize: 16 }], textAlign: center }, { type: text, x: 290, y: 180, width: 190, height: fit-content, text: {{MILESTONE_2_DESC}}, fontSize: 13, textAlign: center } ] } ] }对模板中的占位符与坐标规律做逐一说明便于扩展到 8 个节点占位符含义取值建议{{CHART_TITLE}}图表标题加粗、fontSize 24居中于画布顶部{{DATE_N}}第 N 个里程碑的年份/日期如 2024 Q1fontSize 13-14{{MILESTONE_N_TITLE}}第 N 个里程碑标题加粗、fontSize 16{{MILESTONE_N_DESC}}第 N 个里程碑描述可选fontSize 13更小更浅坐标递推规律对应原文档「先确定里程碑数量计算等距的 x 坐标序列」年份条与卡片统一宽度190x 步长为240190 卡片宽 50 间距即第 N 个节点的x 50 (N-1) × 240同一节点的年份条y56、日期文字y64、卡片y132、标题y150、描述y180纵向层叠垂直间距统一日期文字与箭头色块共用 x/width保证「年份条与卡片等宽、左右对齐」。需要补充的还有两个模板未展开的要素时间轴 connector在根nodes数组中追加一条lineShape: straight的连线贯穿所有节点如from: {x: 50, y: 100}, to: {x: 770, y: 100}每个节点再配一条短竖线如从{x: 145, y: 100}到{x: 145, y: 132}连接卡片连线必须放在根 nodes 数组末尾不能放进 frame 的 children见 elements/connectors.md文字高度用fit-content所有含文字节点标题、日期、卡片标题、描述的 height 均为fit-content因为引擎不支持 overflow写死高度会截断文字见 elements/layout.md 注意事项第 5 条。六、陷阱清单四个必须避开的坑原文档以「陷阱」小节收尾这些是渲染审查对应 routes/dsl.md Step 3 的检查清单时必须重点排查的点节点太多时太拥挤超过 6 个节点时应切换为交替上下布局节点交替分布在时间轴上下方或增大画布宽度画布宽度常用范围 1000-1400px见 elements/layout.md 的常用间距表右侧节点与时间轴末端重叠最后一个节点的x width不要超出画布边界——例如画布 1200 宽、卡片 190 宽时最后一个节点的 x 应满足x 190 ≤ 1200即 x 最大约 1010年份条与卡片不对齐年份条和卡片的x、width 必须完全一致——这是本场景最容易出现的视觉瑕疵根源往往是复制扩展模板时只改了 x 忘了同步 width或年份条与卡片各自采用了不同的步长连线形状误用时间轴必须用straight直线若误用polyline/rightAngle刻度附近的自动避障可能把时间轴绕出弧度由 elements/connectors.md 的坐标轴规则引申。七、端到端落地从 DSL 到真实画板骨架模板产出diagram.json后按 references/lark-whiteboard-workflow.md 的「渲染 写入画板」流程执行完整命令语法见 references/lark-whiteboard-update.mdStep 1本地渲染审查npx -y larksuite/whiteboard-cli^0.2.13 -i diagram.json -o diagram.png用 PNG 做预览验证信息是否完整、布局是否合理、文字有无截断、年份条与卡片是否对齐、时间轴是否笔直。发现问题按上述陷阱清单修复后重新渲染最多两轮。Step 2转换为 OpenAPI 格式并写入画板npx -y larksuite/whiteboard-cli^0.2.13 -i diagram.json --to openapi --format json \ | lark-cli whiteboard update --whiteboard-token board_token \ --source - --input_format raw --idempotent-token 时间戳标识 --as user关键参数说明详见 lark-whiteboard-update.md--whiteboard-token目标画板 tokenwbcnXXX格式需拥有画板编辑权限--input_format rawDSL 产物必须先用 whiteboard-cli 转成 OpenAPI 原生节点格式再以raw写入--idempotent-token幂等 token最少 10 个字符建议使用时间戳 场景标识拼接如1744800000-milestone-1同一次逻辑更新只生成一次重试时原样复用切勿每次重试都重新生成否则会重复写入--as user画板操作默认以用户身份执行参见 SKILL.md 的快速决策首次写入空白画板时无需--overwrite若写入已有内容画板并需覆盖则要附加--overwrite并确认会整板重建。结语里程碑时间线是 lark-whiteboard DSL 路径中最典型的「绝对定位承载语义」场景x 坐标即时间、layout: none容器 固定宽高是前提、箭头 SVG 虚线卡片是视觉骨架、等距步长与严格对齐是质量底线。掌握 scenes/milestone.md 的约束与骨架模板再结合 schema.md、layout.md、connectors.md 的底层规则即可稳定产出可写入飞书画板的版本演进时间线也能轻松迁移到组织大事记、项目排期等同类时间序列图表。【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址: https://gitcode.com/gh_mirrors/cli414/cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考