除 `content` 外没有任何文本键既被求值又被读回 —— `statistic.value` / `card.title` / `button.label` 无法绑定表达式

[yinlianghui]

发现于 #4786 的实施(教学面拆 props 信封),真实 SchemaRenderer 探针实测。这不是文档问题 —— 文档教错正是因为引擎这里有一个真实的洞。

两道闸门,没有一个键同时通过(除 content)

一个值要上屏必须同时:被 SchemaRenderer 求值,且被 renderer 读回。实测两边互不重叠:

写法	求值?	读回?	实测渲染
{ "type": "statistic", "props": { "value": "${data.n}" } }	✅	❌	空 —— props 被 spread 成 React props,StatisticRenderer 读 schema.value
{ "type": "statistic", "value": "${data.n}" }	❌	✅	字面量 ${data.n}
{ "type": "text", "content": "${data.n}" }	✅	✅	99

card.title / button.label / *.description 同理。探针原文(dataSource { total: 99 }):

@@PROBE expr/card-title-ENVELOPE   text=""                    html=... props="[object Object]" title="99" ...
@@PROBE expr/card-title-TOPLEVEL   text="${data.total}"
@@PROBE expr/text-content-TOPLEVEL text="Total: 99"

注意 ENVELOPE 那行:title="99" —— 值确实求出来了(99),只是作为 React prop 落到 DOM 属性上,CardTitle 里仍是空的。求值白做了。

成因(读码)

• packages/react/src/SchemaRenderer.tsx 的 evaluation memo 只处理 content、props.* 和几个谓词键;title/label/value/description 原样透传。
• 同文件 React.createElement(Component, { schema, ...componentProps, ...(evaluatedSchema.props || {}), ... }) —— props 的内容作为 React props 展开,而 ui:* / page:* renderer 一律读 schema.*(packages/components/src/renderers/data-display/statistic.tsx 读 schema.value;layout/card.tsx 读 schema.title;form/button.tsx 读 schema.label)。

后果

statistic 是仪表盘的主力组件,而它没有任何办法绑定一个动态数值 —— 只能由宿主在交给 SchemaRenderer 之前把值算好。教学面此前给出的"搬到 props 里"这个 workaround(protocol.md / page-builder.md / schema-expressions.md 三处成体系地写着)把"渲染出字面量"换成了"渲染出空白",更难诊断。PR(#4786)已把教学面改成如实陈述 + 走 content 或宿主预解析,但契约层面的洞留在这里。

修法方向(需裁决,勿直接猜)

1. 扩大求值面:让 evaluation memo 对一组声明过的文本键(title/label/value/description)也跑模板求值。代价:哪些键算"文本键"需要在 @objectstack/spec / types 里声明清楚,否则又是一套方言。
2. 把 props 并进节点:SchemaRenderer 把 schema.props 合并进 schema 而不是 spread 成 React props。代价:与 element:* 的 readProps 语义冲突,且会把"信封合法"这个已被 教学面成体系教 props 信封,而渲染器从节点本身读键 —— 照 page-builder.md 写出的页面渲染一片空白框 #4786 教学面否定的形态重新变成合法。
3. 维持现状 + 发布期诊断:承认只有 content 可绑定,并对"节点上出现未求值的 ${...}"给出发布期报错。

个人倾向 1 或 3,但这是契约收紧,按 #3972 / #3987 家族先例应由维护者裁。

参考

• 教学面成体系教 props 信封,而渲染器从节点本身读键 —— 照 page-builder.md 写出的页面渲染一片空白框 #4786 / 其 PR(教学面改写,探针实测记录)
• 教学面仍在教未声明的 cols 键(AGENTS.md #5 / skills 两处 / site 营销样例)—— #4001 修了 catalog,生成器还在 #4011 / PR docs(skills,site,agents): 教学面改用声明键 columns,停止教未声明的 cols (#4011) #4785(同一家族:catalog 已上棘轮,教学源未动)

[os-zhuang]

Triage: needs-user-decision, type Feature. Which text keys are expression-bindable is a contract question — the card's three directions each change the accepted authoring surface (per the #3972/#3987 family precedent, human floor).

Four prisms:

1. Platform long-term coherence — direction 1 (a declared text-key evaluation set) closes the evaluate/read-back split with one declared vocabulary; direction 2 (merge props into the node) re-legalizes the envelope shape 教学面成体系教 props 信封,而渲染器从节点本身读键 —— 照 page-builder.md 写出的页面渲染一片空白框 #4786's teaching rewrite just retired — incoherent.
2. Measured business pull — statistic is the dashboard workhorse and today has NO way to bind a dynamic value; the former teaching-face workaround renders blank. Real authoring pull.
3. AI-agent error-resistance — today's state is the worst shape: an AI following the docs renders literals or blanks silently. Direction 3 (publish-time diagnostic on an unevaluated ${…} reaching the DOM) is the loud-refusal floor even if 1 is deferred.
4. Startup scope discipline — direction 1 is a permanent vocabulary obligation; direction 3 is cheap and reversible.

Recommendation: 3 now (loud refusal); 1 only with an explicitly declared, closed key set in spec/types; never 2. Joint axis with #4797 (same SchemaRenderer evaluation contract) — recommend ruling both in one sitting.

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling (2026-08-17, recorded by PM session session_01NYgmGheCzM6NrHZN436Cxf). The maintainer accepted the decision-inbox report's recommendations in full, verbatim: 「同意」. Ruled together with #4797 (same SchemaRenderer evaluation contract):

Ruled: Direction 3 now; Direction 1 deferred with a named restart condition; ⛔ Direction 2 never.

1. Now (dispatchable): a publish/render-time loud diagnostic when an unevaluated ${…} expression reaches the DOM — the silent-literal/silent-blank shape becomes a named refusal pointing at the working channels (content, or host pre-resolution).
2. Deferred — Direction 1 (a declared, closed set of expression-bindable text keys — title/label/value/description — evaluated by the memo): reopens as a spec-first design card when the named restart condition fires — the first real schema-authored dashboard need hits the gap (e.g. an AI-authoring flow that must bind statistic.value and cannot pre-resolve). Until then hosts pre-resolve, which is how every shipped dashboard works today. If reopened: the key set is declared in @objectstack/spec/types as a closed enum, never inferred — and the accept-surface change is fable-tier.
3. ⛔ Direction 2 (merge props into the node) is permanently rejected — it re-legalizes the envelope shape the 教学面成体系教 props 信封,而渲染器从节点本身读键 —— 照 page-builder.md 写出的页面渲染一片空白框 #4786 teaching rewrite just retired.

Label flipped needs-user-decision → pm:queue (the Direction-3 work) in the same stroke; when it lands, this card records the Direction-1 restart condition and closes or holds per the seat's judgement.

---

Generated by Claude Code

[yinlianghui]

PM 排序注记(objectui 分片,session_01GTRjn8xBqp75dk7kFupVRt):方向 3 的实施与 #4799(properties 求值 alias parity)同文件(packages/react/src/SchemaRenderer.tsx evaluation memo)—— 按批内文件不相交纪律,#4799 已先行派发(它落地后 properties 路径不再产生未求值 ${…},方向 3 的诊断不会带着一个已知假阳性源上线)。#4799 落 main 后本卡进下一空席,按分诊席 serial note 重定价。

---

Generated by Claude Code