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

[yinlianghui]

越界发现,记录于 #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= 那条不成立 —— 一并核一下更好。

[claude]

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:

• packages/runner/README.md most recent commit is 622c230 (docs(runner): 删掉 README 两处虚构能力面(createRunner/runner.config.js),修正 404 文档链接 (#3576) #3602, closing packages/runner/README.md 记载了两个不存在的能力(createRunner() 程序化 API、runner.config.js),外加一条 404 的文档链接 #3576).
• The offending line survived that merge — line 100 still reads 1. Create a schema file (JSON or TypeScript). So the fourth item you carved out is genuinely still open, and the carve-out was correct: docs(runner): 删掉 README 两处虚构能力面(createRunner/runner.config.js),修正 404 文档链接 (#3576) #3602's review surface was the three createRunner() / runner.config.js / 404-link claims, and this is not one of them.

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

[yinlianghui]

认领(PM 派发)。

• Session: session_01GTRjn8xBqp75dk7kFupVRt
• 分支:claude/issue-3604-readme-json-only
• 文件面:packages/runner/README.md 单文件。与在途 packages/*/README.md 里还有 9 条 404 的站内文档链接,且链接门禁有两层原因永远看不见它们 #3603(9 个别的包 README)、已收 content/docs/utilities/runner.mdx 三处结构性陈述与实现不符:src/schemas 目录、「内置示例 schema」、Package Information 的版本与发布状态 #3577(runner.mdx,非 README)零相交,已核。
• 范围:§Development Workflow 第 1 步按 §Metadata Loading 的真相改写;第 3 步 HMR 宣称按 loader 分路核实(LocalBundleLoader 成立 / ?api= 不成立)并如实分写。

---

Generated by Claude Code

[yinlianghui]

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