docs(runner): 按实测闭合 §Features 插件断言,三处 main.tsx 订正为 App.tsx (#3619) (#3652)

[yinlianghui]

Fixes #3619
Fixes #3652

content/docs/utilities/runner.mdx 单文件。两单同为该页的插件相关虚构,按 PM 并卡派发,一 PR 双 Fixes。

前提复核(该页被 #3616/#3633/#3646/#3651 连改四轮,按内容锚定而非行号)

两单前提均仍成立,对 origin/main 切点 2ce5c31f0 复核:

• packages/runner/package.json 的 dependencies 里只有 @object-ui/plugin-charts 与 @object-ui/plugin-kanban 两个 plugin-*;而 ls -d packages/plugin-* 有 19 个。
• packages/runner/src/main.tsx 共 18 行,除 license 头外只有 react / react-dom/client / ./App.tsx / ./index.css 四个 import 加一个 createRoot().render(),零个 @object-ui/plugin-*。
• side-effect import 在 packages/runner/src/App.tsx:13-15(@object-ui/components、plugin-kanban、plugin-charts),与单里写的行号完全一致。

各处前后对照

1. §Features(#3619)

原文与同页 §Pre-installed Plugins 自相矛盾:

• 前:- 📦 **Pre-configured** - All official plugins included
• 后:- 📦 **Pre-configured** - The Kanban and Charts plugins, wired up out of the box

措辞与 PR #3644 在 packages/runner/README.md 侧落地的口径对齐(该文件写「Pre-configured with the Kanban and Charts plugins」),不写 popular、不留开放集合暗示。

2. §Use Cases → 1. Plugin Development(#3652,第三处)

• 前:// src/main.tsx
• 后:// src/App.tsx

单正文写「两处」,分诊评论另点出了这条代码注释(共三处)。同一句错误断言的第三次出现,属 #3652 的完成范围,一并订正 —— 留着它这页仍然自相矛盾。

3. §Troubleshooting → Plugin Not Loading(#3652,危害最重的一处)

前:

Check if plugin is imported in `main.tsx`:

import '@object-ui/plugin-yourplugin'

读者打开 main.tsx,那里永远不会有插件 import(连两个预装的都不在),这一步既不能证实也不能证伪,排查线索到此断掉。

后:改成真能证实/证伪的排查动作 —— 指向 src/App.tsx,并明说 main.tsx 只挂载根组件、看不到任何插件 import(把「为什么别去那儿看」写出来,而不是默默删掉);给出两个已知可用的 import 作对照锚点;再按两种可观察症状分叉:

• 页面出现 Unknown component type 盒子(packages/react/src/SchemaRenderer.tsx:381 实际渲染的文案)→ schema 的 type 与插件注册的 key 不一致;
• dev server 对该插件模块返 HTTP 500 → vite.config.ts 缺别名条目。

4. §Adding Custom Plugins 的 npm link(#3652 附注,按实测处置)

分诊评论说「若超出一行改动则应另开卡」。实测下来这里的最小正确改动就不是一行:仅把 npm link 换成 pnpm 写法,仍会留下一份跑不通的步骤 —— 同页正上方 §vite.config.ts 已经写明,任何 @object-ui/* 说明符缺别名条目就会让 dev server 对整条 import 链返 HTTP 500,即 #3575。所以按两个预装插件实际具备的四个接线点补齐(逐条在仓库里验证过):

接线点	证据
package.json 的 workspace:* 依赖	packages/runner/package.json
src/App.tsx 注册 import	App.tsx:14-15
vite.config.ts 别名条目	两个插件均在别名表内
src/index.css 的 @source	index.css:13-14

并点明 npm link 不是本仓该用的工具(严格 pnpm workspace,AGENTS.md §3)。这四点与 PR #3644 已在 README 侧落地的说法一字不差地一致 —— 属口径对齐,非发明。

验证(先预测后运行)

预测与实测一致:

• grep -c "All official plugins" :1 → 0 ✅
• npm link 代码块:2 处 → 0;仅余一处显式否定建议(「npm link is not the tool here」)。
• main.tsx 提及:4 处 → 2 处。此处如实报告偏差:预测写的是「只剩事实正确处」,实测不是「只剩 1 处」—— :77 §Where the Code Lives 的「main.tsx mounts the root」本就正确保留,另一处是我新增的(Troubleshooting 里点明「main.tsx 只挂载根组件、不 import 插件」)。删掉三处错误断言的同时新增一处正确断言,是有意选择:该节的失效模式恰恰是读者会跑去 main.tsx,与其沉默不如指名并说明。

门禁:

$ node scripts/check-doc-links.mjs
Links are valid across 7 scan roots.

$ node scripts/check-control-bytes.mjs
✅  check-control-bytes: OK (scanned 3677 tracked text file(s); skipped 85 binary).

修前修后均绿(7 roots,如实报)。另按控制字节纪律自扫超出门禁扫描面:grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' 对该文件 0 命中,file 判定仍为 Unicode text, UTF-8 text。

未跑 pnpm test / type-check:纯站点文档单文件改动,不触碰任何 TS/构建产物。

无 changeset

站点文档改动,同页前三次改动(#3633 / #3646 / #3651)均为单文件无 changeset,本 PR 沿用同一先例。

邻接通读结果

按要求通读四节邻接找同类新虚构,未发现新的,以下三项经核实均非虚构,故不另开卡:

• §Use Cases 3 的 kanban / bar-chart / data-table 三个 type 都真实注册且在 Runner 里可用(前两者来自两个预装插件,data-table 来自 @object-ui/components,而它正是 App.tsx:13 那行 import)。
• §Add Custom Components 的 ComponentRegistry.register(...) 属实:packages/core/src/index.ts:10 经 export * from './registry/Registry.js' 导出,register() 在 Registry.ts:138。
• §Development Scripts 的 pnpm test 属实:runner 的 scripts.test 为 vitest run。

另:content/docs/utilities/create-plugin.mdx:235-238 也有 npm link,但那页面向的是用 @object-ui/create-plugin 脚手架在自己 app 里做插件的外部作者,整页 npm run build / npm publish 口径自洽,不构成同类错误,故不开卡(已按关键词 + 文件路径搜过 open issue,无重复;#3665 是 create-plugin 包 files 声明的另一回事)。

#3619 提到 §Dependencies 是插件清单的第三处重复 —— 内容本身正确,只是重复,属可选收敛建议;按范围纪律未动。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 7, 2026 7:47pm