企业官网建设流程全解析

图让关系直接可见，但前提是「关系真实存在」。在 ljg-present 的演讲铸造体系中，图表不是装饰配额，而是一类受数据契约约束的语义角色：源中有数据、顺序或关系才画，不补数值曲线，不把并列或相关性擅自升级为因果箭头。本文围绕 ChartSpec.md 展开，完整讲解「原生 chart（bar / line / flow / compare）」与「结构化 Unicode 关系图（diagram）」两类图表的 JSON 数据格式、字段约束、渲染语义与验收标准，并对照 DeckData.ts 的源码校验与 CompositionDeck.json 的可复现样例，让你能写出可被构建工具直接验证、可被浏览器逐项核对的图表数据。读完本文，你将掌握：如何为一段演讲内容选择 chart、diagram 还是 pre；四种原生图表的字段规则与数值约束；diagram 节点/边的布局锚点与语义方向约定；以及图表在 faithful 与 editorial 两种模式下如何通过 sourceIds / derivedFrom 保持溯源。

图表在内容契约中的定位

图表属于 ljg-present 的八个显式语义角色之一（identity、chapter、statement、sequence、quotation、chart、evidence，见 RenderingSpec.md）。每页恰好一个主体，chart 角色只能承载chart或diagram一种主体；这一约束在 DeckData.ts 中被硬性校验：['lines','pre','table','chart','diagram']五个主体字段中必须恰好出现一个。

图表契约的第一条原则是「表达选择」：根据材料的本质决定用哪一种载体。

选择依据是关系是否可以被「结构化」：数量与趋势进入 chart；回路、分支这类节点关系进入 diagram；而需要逐字符保真的代码或原始字符图必须走 pre，绝不能把源码重新画成节点图。这与 RenderingSpec.md 中「真实代码和未授权重绘的源图使用 pre，新关系图采用结构化 diagram」的规定一致——Unicode 连接与自然文字标签分开绘制，正是 diagram 契约的出发点。

图表同样受两种内容模式约束（详见 SKILL.md）：

• faithful（保真排版）：已有投影提纲且未授权改写。补充图必须紧跟原文页，并用derivedFrom引用原文；原文页本身仍保留，不被图替代。
• editorial（演讲编排）：用户已授权提炼、重组或重绘图。可以新图承载同一关系，但以sourceIds追踪原文；上屏文字可在授权范围内改写。

两种模式下共同的底线是：表示可以改变，标签所指、连接方向、数值和结论强度保持有据。代码层面，DeckData.ts 强制sourceIds与derivedFrom互斥，且在 faithful 模式下，带derivedFrom的补充图必须紧跟在引用同一来源的原文页之后（faithful supplemental diagram must follow its source）。

原生 chart：四种 kind 的数据契约

原生 chart 使用如下 JSON 形态（源自 ChartSpec.md）：

{"role":"chart","sourceIds":["SRC-001"],"chart":{"kind":"compare","title":"两种工作","items":[{"label":"生成","text":"形成候选"},{"label":"验证","text":"检查依据"}]}}

四种图表类型

这些数量范围在 DeckData.ts 中逐一实现：compare限定[2,2]（恰好两个条目）、flow限定[2,4]、bar/line限定[2,6]，超出即报chart item count错误。注意flow的text是可选的——如果源文只明示了先后顺序而没有说明文字，可以不写。

公共字段与数值约束

• 公共字段：非空title、非空items、可选note；最多一个 item 使用emphasis:true。
• 附加字段：bar/line可带unit（单位），line可带xLabel/yLabel。
• 数值纪律：数值必须有限（finite），不能用字符串、null 或补零代表缺失；数字与标签保持源顺序。

这些约束在 DeckData.ts 中有精确对应：chart 只允许kind/title/items/note以及bar/line的unit、line的xLabel/yLabel字段；bar/line的每个 item 必须通过Number.isFinite(x.value)，line的 x 必须严格递增（x.x<=c.items[j-1].x即报错）；compare的每个 item 必须有非空text；最多一个 item 使用emphasis:true。也就是说，纵轴含零、x 严格递增、数值有限不是渲染器的自觉，而是构建入口的数据契约，写错数据根本无法通过 BuildDeck.ts 的校验。

一个可运行的 compare 样例

CompositionDeck.json 中的对照页是完整可复现的：

{ "role": "chart", "chart": { "kind": "compare", "title": "两件不同的工作", "items": [ {"label": "生成", "text": "给出候选结果"}, {"label": "验证", "text": "让结果遇到现实"} ] }, "notes": "比较共享一条问题轴。没有第三层总结句，避免重复主张。", "sourceIds": ["SRC-003"] }

对照样张如下。两个条目共享起点与维度，以位置和距离表达差异；不加第三个总结块，也不重复页面主张——这正是 compare 的构图语义。

Unicode 关系图：结构化 diagram 契约

当关系是回路、分支或非线性节点关系时，使用结构化 diagram。它不是把字符画进字符串，而是声明节点、边与布局锚点，由渲染层用 Unicode 连接线绘制。完整契约形态（源自 ChartSpec.md）：

{ "role": "chart", "headline": "反馈回到输入", "sourceIds": ["SRC-002"], "diagram": { "columns": 25, "rows": 7, "nodes": [ {"id": "input", "label": "输入", "caption": "x", "col": 3, "row": 1}, {"id": "result", "label": "结果", "caption": "f(x)", "col": 20, "row": 1} ], "edges": [ {"from": "input", "to": "result"}, {"from": "result", "to": "input", "via": [[20,5],[3,5]], "label": "反馈", "at": [12,5]} ] } }

节点规则

• 节点按id连接；label使用自然文字（中文按自然字距排版），caption是就近的可选释义（如变量名x、f(x)）。
• col/row只是布局锚点，不是数据值；节点的位置语义完全由 edges 的方向表达。
• 节点不强制加框。

DeckData.ts 对网格有硬性校验：columns必须为 3–60 的整数、rows为 2–20 的整数；节点id非空且唯一，label必填非空；节点不能共享同一个锚点（nodes cannot share an anchor），且 col/row 必须落在网格内（node outside diagram grid）。

边规则

• edges的from/to决定语义方向（箭头按此方向绘制），必须连接两个不同的已存在节点。
• via指定路径拐点（网格坐标数组）；未对齐的相邻点以「先水平、再垂直」的直角路径连接。
• label标注过程本身（如「反馈」），at可指定标签位置。
• 共享路径形成交点时，在目标前的可见位置绘制箭头。

校验端要求via与at的每个点都是网格内的整数坐标对（route point outside grid/edge label outside grid）。

连接字符集与文字分层

连接层使用等宽网格字符：─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼ → ← ↑ ↓。文字与线条分层绘制：节点保持自然中文字距，遮让线条，不把中文拉到两个字符单元（这与 DesignSystem.md 中「中文标签保持自然字距，按词组和节点定位，普通文字不模拟终端字符阵列」一致，对应 SKILL.md 的 Gotchas：Unicode 连接线使用等宽网格，中文节点独立排版）。

需要连续对比的图（如同一流程在前后两页反复出现）必须使用相同的 rows/columns、节点锚点和标签规格，保证视觉上的可比性。

一个带回路与分支的完整样例

CompositionDeck.json 的关系页（31×7 网格、四个节点、三条正向边加两条反馈边）是 diagram 的完整范本，其结构为：输入(x) → 处理(f) → 结果(f(x)) → 评价(E)，另有两条反馈边评价→输入（via[[27,5],[3,5]]，标签「反馈」置于[18,5]）与评价→处理（via[[27,5],[11,5]]）。

{ "role": "chart", "headline": "让反馈改变下一轮", "diagram": { "columns": 31, "rows": 7, "nodes": [ {"id": "input", "label": "输入", "caption": "x", "col": 3, "row": 1}, {"id": "process", "label": "处理", "caption": "f", "col": 11, "row": 1}, {"id": "output", "label": "结果", "caption": "f(x)", "col": 19, "row": 1}, {"id": "evaluate", "label": "评价", "caption": "E", "col": 27, "row": 1} ], "edges": [ {"from": "input", "to": "process"}, {"from": "process", "to": "output"}, {"from": "output", "to": "evaluate"}, {"from": "evaluate", "to": "input", "via": [[27,5],[3,5]], "label": "反馈", "at": [18,5]}, {"from": "evaluate", "to": "process", "via": [[27,5],[11,5]]} ] }, "notes": "连接线由 Unicode 绘制。中文节点使用自然字距，释义就近依附节点。回路返回输入与处理。", "sourceIds": ["SRC-004"] }

关系样张如下。注意检查箭头是否完整、回路是否闭合、线条是否穿过无关标签——这正是 ChartSpec 要求的浏览器验收重点。

浏览器验收与可读性

ChartSpec 给出明确的实测检查清单：节点不重叠、回路闭合、箭头完整且方向正确、线段连续、标签和释义相邻。路由穿过无关节点时调整via或位置；节点太多、说明太长时拆分语义，不能靠小字处理。

可读性基线来自 RenderingSpec.md：以 1098×648 视口验证时，图内关键标签与数值的最低有效字号为 26px；复杂图保留标签尺寸并允许横向滚动，普通 flow、compare 纵排。运行时的实际字号、边界与图形标签由 ProbeDeck.js 在浏览器中逐项核对（fit只做最后微调，小于 0.80 时必须重新分页或构图）。

边界：一图一个主要关系

图表契约的边界原则有三条（见 ChartSpec.md 的「边界」一节）：

1. 一图一个主要关系：chart/diagram 不与 lines/table/pre 混作多个主体。每页恰好一个主体的约束由 DeckData 的数据契约保证，不许把图和表格并排堆成「多主体」页。
2. 信息完整性：图题和辅助说明可以省，但理解图所需的信息必须保留。能省略的是重复主张、装饰性外框，不能省略的是方向、标签、数值与关键限定。
3. Unicode 不是配额：Unicode 是关系图的呈现方式，不成为所有页面的配额或装饰。数据契约、浏览器测量和源文核对分别证明其覆盖的部分；而「箭头是否有来源」仍需完整原文审计——结构合法 ≠ 关系真实，这是图表契约区别于一般画图工具的关键立场。

从契约到交付：构建与验证闭环

图表数据不是直接写进 HTML，而是经过 BuildDeck.ts → ValidateDeck.ts → ProbeDeck.js 的验收层次（详见 RenderingSpec.md 与 Workflows/Generate.md）：

1. BuildDeck校验输入契约（dataErrors即覆盖上文所有 chart/diagram 规则）并内嵌资源；
2. ValidateDeck从最终 HTML 反解析数据，核对源内容、构建指纹与离线/零动效；
3. ProbeDeck在浏览器核对实际角色、主对象、字号、边界、图形标签与交互，报告绑定同一 buildId。

完整可运行的复现命令（源自 CompositionReference.md）：

bun Tools/BuildDeck.ts References/CompositionDeck.json /tmp/composition-reference.html bun Tools/ValidateDeck.ts /tmp/composition-reference.html --json

构建时先按 DesignSystem.md 的讲述功能选版式，再按 ChartSpec.md 选载体；chart/diagram 数据进入role:"chart"的页面主体，与statement、evidence等其他角色共享同一套来源溯源（sourceIds/derivedFrom）。图表的「事实边界」由三处共同兜底：数据契约保证结构合法，浏览器测量保证画面成立，源文审计保证箭头有出处——三者缺一不可，静态 PASS 不等于画面成立，图合法也不等于关系有据。