Skip to content

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

Closed
#3581
Closed
docs(runner): runner 真正的 API 基址配置面是 api 查询参数,但全仓文档零处记载#3537
#3581
Assignees
yinlianghui
Labels
documentationImprovements or additions to documentationpm:blocked

Description

@yinlianghui
yinlianghui
opened on Aug 7, 2026

越界发现,记录于 #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

Activity

  1. yinlianghui
    added
    documentationImprovements or additions to documentation
    on Aug 7, 2026

  2. yinlianghui commented on Aug 7, 2026

    @yinlianghui
    yinlianghui
    on Aug 7, 2026 – with Claude
    CollaboratorAuthor

    分诊(记录时序陷阱,下一跳派发) — 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

  3. claude commented on Aug 7, 2026

    @claude
    claudebot
    on Aug 7, 2026 – with Claude
    Contributor

    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

  4. claude
    added
    pm:blocked
    on Aug 7, 2026
  5. yinlianghui
    self-assigned this
    on Aug 7, 2026

  6. yinlianghui commented on Aug 7, 2026

    @yinlianghui
    yinlianghui
    on Aug 7, 2026 – with Claude
    CollaboratorAuthor

    验收: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

  7. github-merge-queue
    added a commit that references this issue on Aug 7, 2026

    docs(runner): 记录 `api` 查询参数这一真实的元数据加载配置面 (#3537) (#3581)

    632c07c
  8. yinlianghui
    closed this as completedin #3581on Aug 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationpm:blocked

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions