content/docs/utilities/runner.mdx 两处叫读者去 src/main.tsx 找/加插件 import,但真实 main.tsx 零插件 import(在 App.tsx),且与同页 §Where the Code Lives 自相矛盾

[yinlianghui]

越界发现,记录于 #3643(§vite.config.ts)实现期间通读该节邻接时。未在该 PR(#3651)中顺手修改 —— 该单锁死在 ### vite.config.ts 单节上,这是同页另一处同类断言。

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

同一页有两处把 src/main.tsx 指认为插件 import 的所在地:

1. ### Adding Custom Plugins 第 2 步 —— 「Import in src/main.tsx:」,后接 import '@object-ui/plugin-yourplugin';
2. ### Plugin Not Loading(Troubleshooting)—— 「Check if plugin is imported in main.tsx」,后接同一行代码。

对照 packages/runner/src/main.tsx 实际内容:该文件共 18 行,除 license 头外只有

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import './index.css'

外加一个 ReactDOM.createRoot(...).render()。零个 @object-ui/plugin-* import。

两个预装插件的 side-effect import 在 packages/runner/src/App.tsx :13-15:

import '@object-ui/components';
import '@object-ui/plugin-kanban';
import '@object-ui/plugin-charts';

为什么这不只是「换个文件名」的小错

同页 §Where the Code Lives 已经把这件事写对了 —— 它写 「App.tsx is that root — it picks the metadata loader …, imports the pre-installed plugins, handles routing」。所以这一页对同一个事实给出了两个互相打架的答案,读者无从判断哪个算数。

危害集中在第 2 处(Troubleshooting)。「插件没加载」的排查步骤是「去 main.tsx 看看 import 在不在」—— 读者打开 main.tsx,那里永远不会有插件 import(连两个预装的都不在),于是这一步既不能证实也不能证伪,排查线索到此断掉;想照着现有写法模仿的人也找不到可模仿的行。

第 1 处(Adding Custom Plugins)危害弱一些:读者若真在 main.tsx 里加一行 side-effect import,由于 main.tsx 先 import App.tsx、注册在 createRoot().render() 之前完成,功能上其实能跑通。所以这一处是「指了个不合仓库惯例、且与本页自述矛盾的位置」,不是硬故障 —— 但它和第 2 处是同一句错误断言的两次出现,应一并处理。

建议

两处统一改为 src/App.tsx,与同页 §Where the Code Lives 对齐;Troubleshooting 那条可顺带点明「预装的两个插件就 import 在 App.tsx 里,可对照」。

顺带(同节,修的人自然会碰到,是否一并处理请 triage 定):§Adding Custom Plugins 第 1 步给的是 npm link / npm link @object-ui/plugin-yourplugin,而本仓是严格的 pnpm workspace(AGENTS.md §3),npm link 在 pnpm workspace 里并非该用的工具。这一条是工具建议不当,与上面的「事实断言错误」不同类,故只作附注。

去重

已按关键词 + 文件路径搜过 open issue,无重复:

• content/docs/utilities/runner.mdx §vite.config.ts 展示的配置在实现里不存在(server.port/open 全无),真实配置的 resolve.alias 表与 build.modulePreload 反被隐去 #3643 / PR docs(runner): §vite.config.ts 改写为指路真实文件 + 点名两个承重不变量 (#3643) #3651:§vite.config.ts,已在途,不覆盖本处。
• content/docs/utilities/runner.mdx §Best Practices 的 Error Boundaries 从 @object-ui/components 导入 ErrorBoundary,但该符号在 app-shell,且 runner 不依赖 app-shell #3635:§Best Practices 的 Error Boundaries 从 @object-ui/components 导入,另一节另一符号。
• content/docs/utilities/runner.mdx Features 写「All official plugins included」,实际只预装 kanban + charts 两个,与同页下方清单打架 #3619:§Features 的「All official plugins included」,是插件数量断言,不是 import 位置断言。
• packages/runner/README.md 的插件清单两处写成开放集合(§Features 的「etc.」、§Pre-installed Plugins 的非插件条目),实际只预装 kanban + charts 两个 #3632:packages/runner/README.md 的插件清单,另一文件。
• packages/runner/vite.config.ts 的 @object-ui/data-objectql 别名指向不存在的包目录（全仓唯一引用） #3593:真实 vite.config.ts 的 data-objectql 别名指向不存在目录,代码侧。

---

Generated by Claude Code

[os-zhuang]

Triage: pm:queue. No domain:* — objectui is a whole-repo seat, so pm-state is the only label this card needs.

Premise verified on origin/main before queueing (the filing is minutes old, but the check is cheap and the repo moves): content/docs/utilities/runner.mdx still points readers at main.tsx in both places — :213 ("Import in src/main.tsx"), :237 (the code comment), and :536 (the Troubleshooting step) — while the pre-installed plugin imports are in packages/runner/src/App.tsx:14. The self-contradiction with §Where the Code Lives (:77) is real as described.

Why queue and not finding: two exact line locations, a stated prescription (repoint both to src/App.tsx, aligned with the page's own §Where the Code Lives), and a user-reachable consequence — the Troubleshooting step sends a reader to a file where the answer can never be, so the debugging path dead-ends. That is a defect with a landing site, not an observation.

Not transferred to the objectstack backlog: it is repo-local docs trivia — not feature-level, not cross-repo, and it does not touch packages/spec — so it stays in this repo's queue under the One-main-backlog rule's local-trivia clause.

On the附注 (the npm link step): left in scope for the taker's judgement rather than split out. It is one section, the fixer will be standing in it, and this repo is a strict pnpm workspace — but it is a different class of error (tooling advice vs. false factual assertion), so if it turns into more than a one-line change it should become its own card rather than grow this one.

The filer's duplicate search reproduces: #3643/#3651, #3635, #3619, #3632, #3593 are all adjacent and none covers these two assertions.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code