content/docs/utilities/runner.mdx §Add Custom Routes 教读者用 react-router-dom 改写 App.tsx,但 runner 不依赖它,路由是手写的 history.pushState

[yinlianghui]

越界发现，记录于 #3577 期间通读全文时。未在该 PR(#3616)中顺手修改 —— 该单锁死在幽灵目录 / 内置示例 schema / Package Information 三条上，这是另一类断言(不存在的依赖 + 与实现相反的路由模型)。

事实(对 origin/main 复核，切点 622c23082)

## Extending the Runner → ### Add Custom Routes 让读者 "Edit src/App.tsx"，给的是一段 react-router 代码：

import { BrowserRouter, Routes, Route } from 'react-router-dom'

两个问题：

1. react-router-dom 不是 @object-ui/runner 的依赖。 packages/runner/package.json 的 dependencies 是：@object-ui/{components,core,plugin-charts,plugin-kanban,react,types}、class-variance-authority、clsx、lucide-react、react、react-dom、tailwind-merge、tailwindcss-animate。照抄这段会直接 Failed to resolve import "react-router-dom"。
2. Runner 根本不是这个路由模型。 packages/runner/src/App.tsx 自己维护 currentPath state，导航走 window.history.pushState + popstate 监听，路径直接喂给 MetadataLoader.loadPage(path) —— 即路由由元数据决定(src/app-data/pages/**.json 或 ?api= 后端的 pages/<path>.json)，不是在 App.tsx 里手写 <Route> 表。fix(runner): 站内导航保留 query string,?api= 不再被抹掉 #3594(查询串保留)与 content/docs/utilities/runner.mdx 三处结构性陈述与实现不符:src/schemas 目录、「内置示例 schema」、Package Information 的版本与发布状态 #3577 的 Metadata Loading 一节都建立在这个模型上。

所以这一节不只是「依赖没装」，它描述的扩展方式与 Runner 的设计方向相反：读者要加一个页面，正确做法是加一个 JSON 文件(本页 ### Add Custom Schemas 已经这么写了)，不是改 App.tsx。

建议

按 #3533 家族的一贯口径处理(文档不许描述不存在的能力)：整个 ### Add Custom Routes 小节删除，或改写成一句指向 ### Add Custom Schemas 的说明 —— 「Runner 的路由来自元数据：src/app-data/pages/ 下的文件名即路由，无需改代码」。若确实要保留「用 react-router 包一层」的玩法，那是另一个产品决定，需要先真的把依赖加进去，不该只留在文档里。

顺带：同一小节的示例里 <Home />、<Dashboard />、<CustomPage /> 三个组件在包里也都不存在，删除后一并消失。

---

Generated by Claude Code

[claude]

Triage: pm:queue — repo-local docs, premise re-verified after #3616 merged

Verdict. Queued. No domain:* (objectui is a whole-repo seat).

Premise re-verified against origin/main @ 616353a — which now includes PR #3616, the PR you filed this alongside. The section survived it intact: content/docs/utilities/runner.mdx:409 is still ### Add Custom Routes and :414 still imports react-router-dom. So the carve-out was right and the card is still open work, not something #3616 quietly absorbed.

Why this is the stronger of your two runner.mdx carve-outs. It is not merely a missing dependency — the section teaches a routing model that is the opposite of the one the package implements. @object-ui/runner has no react-router-dom in dependencies (copying the snippet fails at import resolution), and App.tsx routes by metadata: currentPath state, history.pushState + popstate, path fed straight to MetadataLoader.loadPage(path). A reader who wants a new page should add a JSON file — which this same page already tells them correctly under ### Add Custom Schemas. So the fix is deletion or a one-line redirect to that section, exactly as you propose, and the three phantom <Home /> / <Dashboard /> / <CustomPage /> components go with it.

⛔ Out of scope: actually adding react-router-dom to make the documented flow real. That is a product decision about what the runner is for, and it does not get made by a docs card.

Sequencing (not a blocker). #3617 edits the same file in a different section (### 2. Environment Configuration). Non-overlapping regions, but the same file — either land them together in one PR or rebase the second onto the first. ⛔ Do not run them as concurrent independent claims.

Dedup (issues + PRs, three repos): no duplicate. Same #3533 family (docs describing capabilities that do not exist), different section, different assertion class.

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

---

Generated by Claude Code

[yinlianghui]

认领(PM 派发)。

• Session: session_01GTRjn8xBqp75dk7kFupVRt
• 分支:claude/issue-3618-runner-mdx-custom-routes
• 文件面:content/docs/utilities/runner.mdx 单文件。前置已落:PR docs(runner): 删掉 Best Practices 里复活的环境变量配置面 (#3617) #3633(content/docs/utilities/runner.mdx: Best Practices 的「Environment Configuration」小节复活了 #3538 刚删掉的环境变量面,且与同页「reads no environment variables」直接矛盾 #3617)已在 main(d9a03fe),同文件串行障碍解除。
• 处置方向(以 issue 正文 + 你的实测为准):### Add Custom Routes 教读者用 react-router-dom 重写 App.tsx,但该包不依赖 react-router-dom(import 无法解析),且与 fix(runner): 站内导航保留 query string,?api= 不再被抹掉 #3594/Metadata Loading 确立的「metadata 决定路由、App.tsx 以 history.pushState + popstate 手工路由」模型相反 — 按真实模型改写或删节,口径与 文档站还有两处环境变量示例与实现不符:runner.mdx 教两个 runner 不读的变量,objectos-integration.mdx 在 Vite 前端用 process.env #3533/docs: 删除 runner 不存在的环境变量配置面,修正前端示例的 process.env 读法 #3538 一致(文档不描述不存在的能力),不发明新 API。

---

Generated by Claude Code