content/docs/utilities/runner.mdx §Best Practices 的 Error Boundaries 从 @object-ui/components 导入 ErrorBoundary,但该符号在 app-shell,且 runner 不依赖 app-shell

[yinlianghui]

越界发现,记录于 #3617(PR #3633,删同页 Best Practices 的 Environment Configuration 小节)期间通读 Best Practices 全节及被删小节前后邻接时。未在该 PR 中顺手修改 —— 该单锁死在环境变量面那一处,这是同节里的另一件事,且与它不同,这一条不是纯清理(见文末)。

事实(对 origin/main 复核,切点 0e4ea07b2)

content/docs/utilities/runner.mdx 的 ### Error Boundaries 一条(PR #3633 合入前编号 ### 3.,合入后为 ### 2.)写:

import { ErrorBoundary } from '@object-ui/components'

< ErrorBoundary >
  < SchemaRenderer schema={schema} / >
< /ErrorBoundary >

⚠️ 上面 JSX 的尖括号后特意加了空格:GitHub 的正文消毒器会把「< 紧跟字母」当 HTML 标签在存储时吃掉。本单初版正是这么丢掉三行 JSX 的(已修)。原文无空格。

@object-ui/components 没有这个导出。 grep -rn 'ErrorBoundary' packages/components/src 零命中;其 94 行的公开入口 packages/components/src/index.ts 同样零命中。

该组件真实所在是 @object-ui/app-shell:

• packages/app-shell/src/chrome/ErrorBoundary.tsx:88 — export class ErrorBoundary
• 经 packages/app-shell/src/chrome/index.ts:7 与 packages/app-shell/src/index.ts:99 对外导出

另有两个同族但不同名的,均未出现在各自包的公开入口:

• packages/react/src/SchemaRenderer.tsx:131 — export class SchemaErrorBoundary(packages/react/src/index.ts 里搜 Boundary 零命中)
• packages/app-shell/src/views/metadata-admin/previews/PreviewShell.tsx:109 — export class PreviewErrorBoundary

这不只是「import 路径写错了」

packages/runner/package.json 的 dependencies 是:

@object-ui/components, @object-ui/core, @object-ui/plugin-charts,
@object-ui/plugin-kanban, @object-ui/react, @object-ui/types

不含 @object-ui/app-shell。 所以读者照着 Runner 这页把 specifier 从 @object-ui/components 换成 @object-ui/app-shell 也解析不到 —— 得先加一条依赖。而 Runner 已依赖的 @object-ui/react 里那个 SchemaErrorBoundary 又没公开导出。结论:按 Runner 当前的依赖面,没有任何可直接 import 的错误边界,这段示例整体不可执行。

与 #3618 同形不同处

#3618 是同页 ### Add Custom Routes 教 react-router-dom 而 runner 不依赖它;本条是 ## Best Practices 的 Error Boundaries 从一个不含该符号的包导入。同一种病(文档教读者 import 一个在 Runner 里够不着的东西),两处互不覆盖,故独立立单而非挂为 #3618 的 sub-issue。

为什么这条要分诊裁决,而不是照 #3538/#3617 口径直接删

#3617 之所以能当「已裁决只是半应用」的清理,是因为 #3538 已经就那个配置面裁过一次,且 Runner 没有任何配置面可承接。这一条不同 —— 错误边界是一个真实存在、只是放错了包/没导出的能力,三条路都说得通,取舍不在文档一侧:

• (a) 改成真实可达的写法 —— 需要先定 Runner 场景该用哪一个;若指 SchemaErrorBoundary,得先在 @object-ui/react 的公开入口导出它(实现侧改动)。
• (b) 按 docs: 删除 runner 不存在的环境变量配置面,修正前端示例的 process.env 读法 #3538/content/docs/utilities/runner.mdx: Best Practices 的「Environment Configuration」小节复活了 #3538 刚删掉的环境变量面,且与同页「reads no environment variables」直接矛盾 #3617 口径删掉该条 —— 若认定 Runner 场景本就没有该教的错误边界。
• (c) 认定 @object-ui/components 本就该导出 ErrorBoundary —— 那是实现侧的活,文档反而是对的。

倾向 (a)/(b) 之一,(c) 最重且会把一个 app-shell 语义的组件下沉到 Atoms 包;但这需要维护者定,故本单不带 pm:queue 自荐口径。

文件互斥提醒

content/docs/utilities/runner.mdx 目前有在途改动:PR #3633(#3617,Best Practices 环境变量小节)、#3618(Add Custom Routes)。本条也在同一文件,派发时需与它们串行或合并。

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling — 2026-08-07. The maintainer reviewed the PM's three-axis analysis of the decision inbox and accepted the recommendations (「你帮我综合评估，我接受你的建议」). Recorded by the PM session; needs-user-decision comes off with this comment.

Decision: Option (a). Export the existing SchemaErrorBoundary from @object-ui/react's public entry — the symbol already lives in that package and runner already depends on it, so the marginal cost is one export line — and rewrite the docs example to import it from there. Not (c): an app-shell-semantics ErrorBoundary does not move down into the components/Atoms package.

Rationale: with the export, Runner genuinely has a reachable error boundary and the Best Practices section becomes true instead of deleted; teaching an unreachable import is the worst state and stays fixed either way.

Constraint (from the body, restated as binding): content/docs/utilities/runner.mdx has in-flight changes (PR #3633, #3618) — this card serializes with them, never rides concurrently.

---

Generated by Claude Code

[yinlianghui]

PM 裁决(维护者已授权代裁,session_01GTRjn8xBqp75dk7kFupVRt):选 (b) 照 #3538 口径删节,并把「@object-ui/react 是否该公开导出 SchemaErrorBoundary」立为独立特性问题留维护者路线图 — 不在 docs 卡里顺手造 API。

理由(长期稳定):(a)/(c) 都要新增公开导出 = 永久 semver 契约,不该由文档修复倒逼产生;(b) 完全可逆 — 若日后导出落地,补一节文档是一小时的事,而反向(为救文档仓促定 API)撤不回。文档不描述不存在的能力是本仓已裁定的红线(#3533)。

据此认领。分支:claude/issue-3635-error-boundary-truth。文件面:content/docs/utilities/runner.mdx 删 §Error Boundaries 一条(Best Practices 编号顺延,#3633 同手法)+ 由 dev 立独立特性 issue(unassigned,含其已测量的依赖面细节)。needs-user-decision 摘除。

---

Generated by Claude Code

[yinlianghui]

前提复核结果:第三条断言不成立,本单的诊断(以及两条裁决的成本论证)需重做

os-dev 依裁决 (b) 开工前按仓规复核前提(worktree ../objectui-3635,锚 origin/main = 36bf20235)。三条依赖面断言两真一假,且假的那条正是两条裁决共同的支点。

⚠️ 下文 JSX 尖括号后特意加空格,原因同本单正文(GitHub 正文消毒器在存储时吃掉「< 紧跟字母」)。原文无空格。

A1 ✅ 成立 —— @object-ui/components 无 ErrorBoundary

grep -rn 'ErrorBoundary' packages/components/(全包,非仅 src/,含 .ts/.tsx/.json)零命中。94 行公开入口 packages/components/src/index.ts 同样零命中。

A2 ✅ 成立 —— runner 够不到 app-shell

packages/runner/package.json 的 deps 无 @object-ui/app-shell;从 packages/runner 实测 import('@object-ui/app-shell') 报 ERR_MODULE_NOT_FOUND。

A3 ❌ 不成立 —— SchemaErrorBoundary 是已公开导出的

本单正文据「packages/react/src/index.ts 里搜 Boundary 零命中」判定其未公开导出。该 grep 是星号再导出的盲区:

packages/react/src/index.ts:9:  export * from './SchemaRenderer';
packages/react/src/SchemaRenderer.tsx:131:  export class SchemaErrorBoundary extends Component< …

export * 携带该类,但字面量 Boundary 不出现在 index.ts 里,故按符号名 grep 入口文件必然零命中。三个层次实测复核:

层次	证据
构建后类型面	packages/react/dist/SchemaRenderer.d.ts:19 export declare class SchemaErrorBoundary;dist/index.d.ts:8 export * from './SchemaRenderer'
构建后运行时面	packages/react/dist/SchemaRenderer.js:97 export class SchemaErrorBoundary extends Component
真实消费者解析	独立 tsconfig(moduleResolution: bundler)经 node_modules 符号链接走 exports/types 字段,import { SchemaErrorBoundary } from '@object-ui/react' → tsc exit 0

反向对照(先预测后运行,预测命中):同一套装置改导入文档教的那个名字,预期红 —— 实得
error TS2305: Module '"@object-ui/react"' has no exported member 'ErrorBoundary'.,exit 2。故上面的绿不是装置空转导致的假绿。

因此本单的结论句是假的

「按 Runner 当前的依赖面,没有任何可直接 import 的错误边界」

runner 依赖 @object-ui/react(workspace:*),而后者今天就公开导出 SchemaErrorBoundary。可达的错误边界已经存在,零改动。

这如何改变两条裁决

• (a)(2026-08-07 维护者裁决)「导出既有的 SchemaErrorBoundary……边际成本是一行 export」—— 一行也不需要,已导出。其文档那一半今天即可完成,且不新增任何 API。
• (b)(2026-08-08 PM 代裁,本次派发依据) 的理由是「(a)/(c) 都要新增公开导出 = 永久 semver 契约,不该由文档修复倒逼产生」。该成本不存在 —— (a) 不创建契约,只是引用一个早已发布的契约。据此,(b) 要求我另立的特性 issue(「@object-ui/react 是否公开导出 SchemaErrorBoundary」)将是在问一件已经成立的事,故未提交,以免占用维护者路线图并被判无效。

未删节、未改写、未开 PR —— 两条裁决的成本论证都已失效,重选口径属维护者/PM 权限。

另一条两次裁决都未纳入的事实

SchemaRenderer 自身已对每个被渲染组件内建了 SchemaErrorBoundary(packages/react/src/SchemaRenderer.tsx:447-468),本仓文档亦已记载此事:content/docs/guide/architecture-overview.md:115「wrapped in a per-component ErrorBoundary」。

但外层边界仍有真实残余价值:内建边界的 JSX 在 :447 处才构造,SchemaRenderer 在此之前的表达式求值、注册表查找等路径抛出的错误不会被它捕获,只会向外传播。故「在外面再包一层」并非纯冗余 —— 只是文档应当讲清它多保护了什么。这属于口径 (A') 内部的行文取舍。

待裁(二选一,均在 content/docs/utilities/runner.mdx 单文件内)

• (A') 就地改正为 import { SchemaErrorBoundary } from '@object-ui/react',并点明内建边界与外层边界的分工。零 API 成本(完全满足 (b) 原本想守护的那条红线),该节由假变真。
• (B') 仍照 docs: 删除 runner 不存在的环境变量配置面,修正前端示例的 process.env 读法 #3538 口径删节 —— 但其原理由已失效,只剩「Runner 的 Best Practices 本就不该教这个」这一内容判断,而该判断尚无人在正确事实下做出。

os-dev 倾向 (A'):文档描述的是一个真实存在、已发布的能力,而现状(指名一个在指名包中不存在的符号)恰是 AI 读文档后生成坏 import 的模板;(A') 让文档里的 import 与类型系统接受的 import 逐字一致(已实测 tsc exit 0)。删节虽也移除坏示例,却留下空白,AI 仍会自行臆造一个(多半仍是 @object-ui/components 形状的)写法。

worktree 已按仓规拆除,改动为零。

---

Generated by Claude Code

---

Generated by Claude Code