Skip to content

packages/runner/README.md §Development Workflow 教读者写 TypeScript schema 文件,但两个 loader 都只认 JSON #3604

Closed
#3621
Closed
packages/runner/README.md §Development Workflow 教读者写 TypeScript schema 文件,但两个 loader 都只认 JSON#3604
#3621
Assignees
yinlianghui
Labels
documentationImprovements or additions to documentationpm:dispatched

Description

@yinlianghui
yinlianghui
opened on Aug 7, 2026

越界发现,记录于 #3576(清 runner README 的两处虚构能力面)期间通读全文时。未在该 PR(#3602)中顺手修改 —— 该 issue 锁死在 createRunner() / runner.config.js / 404 链接这三条,这是第四处,属另一件事。

事实(对 origin/main + PR #3602 改后全文复核)

packages/runner/README.md 的 ## Development Workflow 第 1 步:

1. Create a schema file (JSON or TypeScript)

runner 没有任何路径能加载 TypeScript 写的 schema:

  • LocalBundleLoader(packages/runner/src/lib/MetadataLoader.ts:26-28)只 glob JSON: 
    private appGlob   = import.meta.glob('../app-data/app.json');
private pagesGlob = import.meta.glob('../app-data/pages/**/*.json');
private rootGlob  = import.meta.glob('../app-data/*.json');
  • NetworkLoader(同文件 89-103 行)只 fetch 固定的 .json 路径:${base}/app.json、${base}/pages${path}.json,并且直接 res.json()。

同一个 README 的 ## Metadata Loading 一节(#3537 / PR #3581 补、#3594 又改过)已经把真相写清楚了:元数据要么是 src/app-data/**/*.json,要么是 ?api= 指向的后端返回的 JSON。所以第 1 步与本文件自己的另一节直接矛盾。

顺带,第 1 步也没说文件该放哪 —— 按 §Metadata Loading,src/app-data/ 是 git-ignored 且新 clone 下不存在的目录,读者照第 1 步在别处建文件不会有任何效果(每次加载返回 null,页面渲染成 404)。

建议

与 #3533 同源(文档不许描述实现里不存在的能力),但比那几条轻:把第 1 步改成与 §Metadata Loading 一致的说法即可,例如"在 src/app-data/ 下建 app.json 与 pages/*.json(或用 ?api= 指向一个供这两类 JSON 的后端)",而不是"Create a schema file (JSON or TypeScript)"。

同一节第 3 步 "Edit the schema - changes reload automatically" 对 LocalBundleLoader 走 import.meta.glob 这条路是成立的(Vite HMR),对 ?api= 那条不成立 —— 一并核一下更好。

Activity

  1. claude commented on Aug 7, 2026

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

    Triage: pm:queue — repo-local docs correction, premise re-verified

    Verdict. Concrete, single-file, and the fix is stated. Queued. No domain:* (objectui is a whole-repo seat).

    Premise re-verified against origin/main, after #3602 merged. This matters here more than usual, because the card was written mid-flight against a PR that has since landed:

    Scope. Rewrite step 1 to agree with this file's own ## Metadata Loading section — JSON under src/app-data/ (app.json, pages/*.json), or a backend serving those two shapes behind ?api=. The self-contradiction is the whole defect: neither LocalBundleLoader's three import.meta.glob patterns nor NetworkLoader's fixed .json fetches have any path that loads a TypeScript-authored schema, and the same README already says so correctly one section down.

    Second item accepted into the same card (same section, same review surface, would be wasteful to split): step 3's "changes reload automatically" holds for the LocalBundleLoader path via Vite HMR but not for ?api=. Qualify it rather than deleting it.

    Worth keeping in the PR body, since it is the part a reader will hit next: step 1 also never says where the file goes, and src/app-data/ is git-ignored and absent from a fresh clone — so a reader following the current text lands on a page that renders 404 with no error explaining why.

    Dedup (issues + PRs, three repos): no duplicate. Same family as #3533 and #3576 (documentation describing capabilities the implementation does not have), different line, different file region — and #3576 is closed by the merged #3602.

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

    Generated by Claude Code

  2. claude
    added
    pm:queue
    on Aug 7, 2026
  3. yinlianghui
    added
    documentationImprovements or additions to documentation
    pm:dispatched
    and removed
    pm:queue
    on Aug 7, 2026
  4. yinlianghui
    self-assigned this
    on Aug 7, 2026

  5. yinlianghui commented on Aug 7, 2026

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

    认领(PM 派发)。

    Generated by Claude Code

  6. yinlianghui commented on Aug 7, 2026

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

    验收 ACCEPT → PR #3621(session_01GTRjn8xBqp75dk7kFupVRt)。

    已核:单文件 +14/−2,CI 相关检查全过(Bundle Analysis 与 markdown 无关);预测 P1–P3 全中,§Compatibility 的 TypeScript 版本要求行属合法幸存,保留正确。

    裁决记录:

    1. HMR 偏离接受,且是本单精神的正确延伸:派单预设「LocalBundleLoader 侧可断言自动热更」,dev 实测后只写了代码可证的部分(JSON 进 Vite module graph、不需重启),拒绝在不起服务的情况下断言「自动出现在屏幕上」(react-refresh 边界 + useEffect 依赖不变,可能被吸收)。写未经确认的机制断言正是 文档站还有两处环境变量示例与实现不符:runner.mdx 教两个 runner 不读的变量,objectos-integration.mdx 在 Vite 前端用 process.env #3533/packages/runner/README.md §Development Workflow 教读者写 TypeScript schema 文件,但两个 loader 都只认 JSON #3604 要清的虚构 — 这个拒绝对。
    2. 不跑 vitest/type-check 的判断成立(markdown 不入任何代码路径,CI paths-ignore 佐证)。
    3. 新发现 packages/runner/README.md §Features 的「Hot Reload - Automatic reload on schema changes」未按 loader 分路,?api= 那条不成立 #3620(§Features 的无条件 Hot Reload 宣称,同一句换了位置)入池,⚠️ 同文件串行等本 PR 落 main。

    Generated by Claude Code

  7. yinlianghui
    closed this as completedin #3621on Aug 7, 2026
  8. akarma-synetal
    added 3 commits that reference this issue on Aug 10, 2026

    docs(runner): 删掉 runner.mdx 的幽灵目录与「内置示例 schema」断言,重写 Package Informat…

    616353a

    docs(runner): README §Development Workflow 按两个 loader 的真相改写第 1、3 步 (o…

    8d5418e

    docs(runner): README §Features 的 Hot Reload 按两个 loader 分路限定 (objectst…

    8098c85
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:dispatched

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions