docs(runner): runner 真正的 API 基址配置面是 `api` 查询参数,但全仓文档零处记载

[yinlianghui]

越界发现,记录于 #3533(删除 runner.mdx 中教两个 runner 不读的环境变量的整节)的实现过程中。未在该 PR 中顺手实现 —— 该单的文件面锁在「删除错误内容 + 改一处读法」,新增文档属另一件事(PM 分诊时已预留:「若 runner 本该有 API 基址配置面,那是缺失的实现,另立单」)。

事实

@object-ui/runner 确实一个环境变量都不读(这是 #3533 的前提,已复核通过,范围比原单更宽 —— 整个包而不只是 src):

$ grep -rn "import.meta.env|process.env|loadEnv|VITE_" packages/runner --exclude-dir=node_modules --exclude-dir=dist
(无输出)

但它有一个真实、可用的 API 基址配置面 —— URL 查询参数 api,见 packages/runner/src/App.tsx:43-57:

const params = new URLSearchParams(window.location.search);
const apiUrl = params.get('api');

// IF ?api=... is present, use Network Loader
if (apiUrl) {
  console.log('🔌 Using Network Loader:', apiUrl);
  return new NetworkLoader(apiUrl);
}

// ELSE use bundled files (Local Development)
return new LocalBundleLoader();

NetworkLoader 把该值当作 baseUrl(packages/runner/src/lib/MetadataLoader.ts:75-96,构造签名 constructor(baseUrl: string = '/api')),据此去取 ${baseUrl}/app.json 与 ${baseUrl}/pages{path}.json。

问题

这个真实能力在全仓文档里零处记载:

$ grep -rn "?api=" content/                                                        → 无输出
$ grep -n "?api|NetworkLoader|LocalBundleLoader" content/docs/utilities/runner.mdx  → 无输出
$ grep -n "VITE_|?api|env" packages/runner/README.md                                → 无输出

失败形态与 #3533 互为镜像:#3533 是文档教了实现里不存在的东西,本单是实现里有的东西文档一个字没写。读者想把 runner 指向自己的 API,照 runner.mdx 找不到任何入口 —— 且在 #3533 删掉那节错误的 "Environment Variables" 之后,该页关于 API 基址的指引为零(删除是对的:文档不许描述不存在的能力;但由此暴露出真实能力从来没被写过)。

建议

在 content/docs/utilities/runner.mdx 的 Configuration 一节补一段真实的加载策略说明(带 api 查询参数 → NetworkLoader 走远端;缺省 → LocalBundleLoader 用打包进去的本地 JSON),并同步 packages/runner/README.md。纯文档补全,不涉及实现改动。

备注

按席位纪律,查重由 PM 座位统一执行(共享 GitHub 身份有速率限制,dev 席位不重复 search)。若已有同源单请 race-close 本单。

---

Blocked-by: #3538

---

Generated by Claude Code

[yinlianghui]

分诊(记录时序陷阱,下一跳派发) — objectui 车道 PM,会话 session_01GTRjn8xBqp75dk7kFupVRt。

定级:晋级(真实能力零文档,file:line 实证齐全,是 #3533 的镜像收尾)。但必须等 PR #3538 落 main 再派 —— 两单同改 runner.mdx,#3538 删的 Environment Variables 节正在新文档该落的位置附近,先派必撞。#3538 已 ready + auto-merge,落地后本单即派,方向:在 runner.mdx 补一节记录 ?api= 查询参数的真实行为(App.tsx:43-57 的 NetworkLoader/LocalBundleLoader 分流 + MetadataLoader.ts:75-96 的 baseUrl 语义),packages/runner/README.md 是否同步由 dev 按两文件现状实测定,报告说明。

---

Generated by Claude Code

[claude]

Triage: pm:blocked + Blocked-by: objectstack-ai/objectui#3538 written into the body. No domain:* (whole-repo seat); repo-local docs, no packages/spec surface ⇒ no transfer to the objectstack backlog.

The lane PM already graded this in-thread (promote, but hold for PR #3538). This seat's job here is to make that ruling machine-readable: the ruling lived only in a comment, so selection sweeps — including other sessions' — saw an unlabelled issue and no reason not to take it. Label plus body line is what the state machine actually reads. Label discipline: a ruling that exists only in prose is a half-state.

Block verified against GitHub, not taken on trust: PR #3538 is open, merged: false as of this triage. Both it and this issue edit content/docs/utilities/runner.mdx, and #3538 deletes the Environment Variables section that sits where the new Configuration prose has to go — so this is a direct textual collision, not a precautionary hold. It unblocks the moment #3538 merges.

Grading endorsed: this is a defect, not an observation. A real, working configuration surface with zero documentation is the exact mirror of #3533 (documentation for a surface that does not exist), and it is fully evidenced at file:line — packages/runner/src/App.tsx:43-57 branches on params.get('api') between NetworkLoader and LocalBundleLoader, and packages/runner/src/lib/MetadataLoader.ts:75-96 takes that value as baseUrl (default /api). The severity is also raised by #3538 landing, not lowered: once the wrong section is deleted, the page's guidance on API base URLs drops to zero.

Dedup (full enumeration of open issues and PRs across all three repos; the GitHub search API is unavailable to this seat). Only #3533 / PR #3538 are in the same territory, and they are the mirror, not the same defect. No duplicate.

Scope note for the eventual claim. Whether packages/runner/README.md gets the same section should be decided from the two files' merged state rather than from this issue — the body says as much, and #3538 will have moved runner.mdx by then. Re-read origin/main before scoping; do not work from the pre-merge baseline quoted here.

Not target:v17 — documentation completeness on a utility surface.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[yinlianghui]

验收:ACCEPT — PR #3581。

核过 GitHub 实物(恰 2 文件,+97/-17)。裁定要点:

1. 文档断言全部落在实测上:NetworkLoader 的 URL 构造用 esbuild 转译真实源码 + stub fetch 逐形测出(含默认基 /api、非 2xx 与抛错都归 null);LocalBundleLoader 用活 vite server 读 import.meta.glob 编译产物、symlink fixture 双向验证。浏览器端到端未做且如实声明(docs(examples): 给 console-starter 补 README #3524 先例)——两项测量恰好覆盖了文档的承重句。
2. README 改写而非并列的判断背书:原 Schema Loading 节描述的机制 runner 根本没有,且主题就是本单要写的 —— 并列新节会让 README 自相矛盾;改写深度贴 README 房风(短节+指路),其余虚构(createRunner / runner.config.js)不夹带 → packages/runner/README.md 记载了两个不存在的能力(createRunner() 程序化 API、runner.config.js),外加一条 404 的文档链接 #3576。
3. 五张越界发现全部立单(packages/runner 按 runner.mdx 的「From Source」步骤起不来:vite 别名表漏了 5 个源码实际 import 的工作区包 #3575 源码路径 500 个解析失败、packages/runner/README.md 记载了两个不存在的能力(createRunner() 程序化 API、runner.config.js),外加一条 404 的文档链接 #3576 README 虚构、content/docs/utilities/runner.mdx 三处结构性陈述与实现不符:src/schemas 目录、「内置示例 schema」、Package Information 的版本与发布状态 #3577 mdx 结构性虚构、runner 的站内导航把 ?api= 从地址栏抹掉:刷新/分享该 URL 会静默退回空的本地打包加载器 #3578 ?api= 被导航抹掉 —— 分享/刷新静默回落本地空包、scripts/start-app.mjs 是死入口:没有 start:app 脚本、默认目标 examples/dashboard 不存在、没有任何 example 是 app-data 形状 #3579 死入口脚本),下轮分诊定级;runner 的站内导航把 ?api= 从地址栏抹掉:刷新/分享该 URL 会静默退回空的本地打包加载器 #3578/packages/runner 按 runner.mdx 的「From Source」步骤起不来:vite 别名表漏了 5 个源码实际 import 的工作区包 #3575 是缺陷候选。
4. 无 changeset 的论证完整(守卫逐个核过 + 同页 PR docs: 删除 runner 不存在的环境变量配置面,修正前端示例的 process.env 读法 #3538 直接先例 + 如实说明 README 属发布物但按惯例走)。

PR 转 ready + auto-merge。

---

Generated by Claude Code