docs(runner): 删掉 README 两处虚构能力面(createRunner/runner.config.js),修正 404 文档链接 (#3576)

[yinlianghui]

Fixes #3576

按 #3533 的口径(文档不许描述实现里不存在的能力)清掉 packages/runner/README.md 的两个虚构能力面,并修正一条 404 的文档链接。改动只落在这一个文件。

三处处置与零命中证据

1. §Programmatic Usage(原 41-50 行)—— 整节删除,并把上方 §Installation 改写成 runner 的真实用法。

$ git grep -n "createRunner" -- .
packages/runner/README.md:41:import { createRunner } from '@object-ui/runner';
packages/runner/README.md:43:const runner = createRunner({

全仓仅此两行,且 packages/runner/package.json 没有 main / module / exports / types 任何一个字段(files 只有 dist / README.md / CHANGELOG.md / LICENSE),所以 import ... from '@object-ui/runner' 无从解析 —— 这个包是 index.html + src/main.tsx 的 Vite 应用,不是库。

选了 issue 给的第二个选项(改写为真实用法)而不是纯删,原因是纯删会留下一个孤儿:上方 ## Installation 教的 pnpm add @object-ui/runner 只在"可 import"的前提下才成立,而 issue 正文已把它点名为同一处虚构的连带面("因此也是误导:装了也没有可 import 的入口")。现在合并为一节 ## Running the Runner,与 content/docs/utilities/runner.mdx 的同名小节口径一致(clone → pnpm install → pnpm --filter @object-ui/runner dev),原来的 pnpm dev / build / preview 三条命令原样保留在下半段。删掉 ### Programmatic Usage 后 ### As a Development Tool 成了唯一的三级标题,一并拍平。

2. §Configuration(原 98-112 行)—— runner.config.js 删除,改写为真实的两个配置面。

$ git grep -n "runner\.config" -- .
packages/runner/README.md:100:Create a `runner.config.js` file to customize the runner:

同样零代码引用(含未跟踪文件的全盘 grep 也只有这一行)。改写后指向实测存在的两处:vite.config.ts(构建选项 + 让 runner 直接从 monorepo 源码启动的别名表;dev server 用 Vite 默认端口 5173,靠 Vite 自己的 flag 改)与 ?api= 查询参数(指回本 README 已有的 §Metadata Loading 锚点,不重复叙述)。这与 #3594 刚落的 §Metadata Loading 那句"it reads no environment variables and no config file"互相印证;#3538 此前已清掉环境变量那一面,这是最后一处虚构配置面。

3. §API Reference 的链接(原 167 行)—— /docs/runner → /docs/utilities/runner。

$ git grep -n "objectui.org/docs/runner" -- .   # 改动前:packages/runner/README.md:167

路由核对(人工,理由见下):content/docs/runner.* 不存在;content/docs/utilities/runner.mdx 存在,且 content/docs/utilities/meta.json 的 pages 里列了 runner,content/docs/meta.json 的 pages 里列了 utilities。同一 README 底部 ## Links 的 Documentation 一条本来就是这个 URL,package.json 的 homepage 也是 —— 现在三处一致。

顺带把标题 ## API Reference 改成 ## Documentation:这一节的正文本来就是"detailed documentation",而本 PR 刚刚确认这个包没有可引用的 API,留着 API Reference 是被删掉那套"库"叙事的最后残留。这是本 PR 唯一一处超出三条 issue 字面的改动,单独在此声明。

改动后三条 grep 全部零命中:

$ git grep -n "createRunner" -- .        -> (无输出)
$ git grep -n "runner\.config" -- .      -> (无输出)
$ git grep -n "objectui.org/docs/runner" -- .  -> (无输出)

全文一致性核对

今天有三个 PR 动过这个文件(#3581 / #3594,以及本 PR),所以通读了改后全文:开头第 3 行"standalone development server and runtime"、§Features 的"Built-in Vite development server"与新的 §Running the Runner 同调,全篇不再有"可 import 的库"这一叙事;新 §Configuration 与 §Metadata Loading 不冲突也不重复;#metadata-loading 锚点对应 ## Metadata Loading 标题,有效。另确认没有任何文件链接到本 README 的旧锚点(git grep "runner/README\|#programmatic-usage\|#as-a-development-tool" 只命中 CHANGELOG 里一句无关文字),所以拍平标题不会打断站内链接。

通读时发现 §Development Workflow 第 1 步"Create a schema file (JSON or TypeScript)"与 §Metadata Loading 不符(两个 loader 都只认 JSON:import.meta.glob('../app-data/**/*.json') 与 fetch(base + '/pages/x.json'))。不在本 issue 的三条范围内,未在本 PR 修改,已另开 issue 记录。

验证

$ node scripts/check-control-bytes.mjs
✅  check-control-bytes: OK (scanned 3641 tracked text file(s); skipped 85 binary).

$ node scripts/check-doc-links.mjs
Links are valid across 3 scan roots.

$ pnpm exec vitest run scripts/ --maxWorkers=2
 Test Files  16 passed (16)
      Tests  275 passed (275)

$ node scripts/check-changeset-fixed.mjs      # CI 的 changeset-check
✅  All workspace packages are in the changeset fixed group.
$ node scripts/check-changeset-no-major.mjs   # changeset-guard
✅  No changeset declares a `major` bump.

$ grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' packages/runner/README.md   # 门禁之外自查
(无命中;file(1) 报 UTF-8 text)

⚠️ 链接门禁看不见这条修复,证据只能是上面的人工路由核对。 两层原因,都实测过:scripts/check-doc-links.mjs 的 SCAN_ROOTS 只有 content/docs / examples / 根 README.md,packages/**/README.md 不在其中;而且即使在其中也没用 —— judgeHref() 在 check-doc-links.mjs:552 对任何带 scheme 的 href 直接 return null,唯一例外是 SELF_REPO_BLOB_RE(本仓 github blob/tree URL),站内绝对地址 https://www.objectui.org/docs/... 从不做路由校验。所以 docs:check-links 那句绿是"没扫到",不是"扫过且通过"。这个盲区在别的包 README 上已经兑现成 9 处死链,已另开 issue。

Changeset

无。 按 #3581 的先例(同样是 packages/runner/README.md + docs 的纯文档 PR,无 changeset)。核对过没有门禁反对:CI 的 changeset-check 跑的是 check-changeset-fixed.mjs(校验所有包在 fixed group 里,不要求每个 PR 带 changeset),changeset-guard 跑的是 check-changeset-no-major.mjs(只拦 major),两条本地都绿。README 确实进 npm tarball(files 含 README.md),但改的是纯错误叙述,没有版本语义。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 7, 2026 3:40pm

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Main entry (gzip)	28.1 KB	350 KB
Entry file	index-CVz6ARkO.js	—
Status	PASS	—

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (index.js)	8.66KB	3.13KB
app-shell (runtime-config.js)	7.42KB	2.32KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	7.57KB	2.97KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	1.17KB	0.53KB
auth (AuthProvider.js)	22.10KB	4.37KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	12.21KB	3.45KB
auth (LoginForm.js)	18.13KB	5.39KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.64KB	2.21KB
auth (SocialSignInButtons.js)	9.60KB	3.89KB
auth (UserMenu.js)	3.40KB	1.22KB
auth (auth-gate-events.js)	1.29KB	0.66KB
auth (authStyles.js)	5.04KB	1.72KB
auth (createAuthClient.js)	35.76KB	9.11KB
auth (createAuthenticatedFetch.js)	4.37KB	1.69KB
auth (index.js)	2.35KB	1.07KB
auth (org-roles.js)	6.66KB	2.78KB
auth (phone-identifier.js)	1.11KB	0.66KB
auth (types.js)	0.59KB	0.35KB
auth (useAuth.js)	4.91KB	0.87KB
auth (useIsWorkspaceAdmin.js)	1.61KB	0.85KB
collaboration (CommentThread.js)	26.07KB	7.56KB
collaboration (LiveCursors.js)	3.17KB	1.27KB
collaboration (PresenceAvatars.js)	6.49KB	2.64KB
collaboration (PresenceProvider.js)	2.79KB	1.13KB
collaboration (index.js)	1.65KB	0.73KB
collaboration (useCollaborationTranslation.js)	6.05KB	2.52KB
collaboration (useCommentSearch.js)	1.98KB	0.88KB
collaboration (useConflictResolution.js)	7.75KB	1.86KB
collaboration (useMentionNotifications.js)	1.81KB	0.68KB
collaboration (usePresence.js)	6.33KB	1.84KB
collaboration (useRealtimeSubscription.js)	7.91KB	2.01KB
components (index.js)	480.72KB	105.64KB
core (index.js)	2.96KB	1.13KB
create-plugin (index.js)	9.28KB	2.98KB
data-objectstack (index.js)	137.51KB	35.11KB
fields (index.js)	230.87KB	56.83KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (currency.js)	1.22KB	0.64KB
i18n (i18n.js)	4.32KB	1.77KB
i18n (index.js)	2.65KB	1.06KB
i18n (pickLocalized.js)	1.70KB	0.83KB
i18n (provider.js)	9.48KB	3.27KB
i18n (useObjectLabel.js)	26.14KB	6.07KB
i18n (useSafeTranslation.js)	4.52KB	1.96KB
layout (index.js)	38.53KB	10.71KB
mobile (MobileProvider.js)	0.92KB	0.49KB
mobile (ResponsiveContainer.js)	0.94KB	0.38KB
mobile (breakpoints.js)	1.51KB	0.70KB
mobile (createOfflineDataSource.js)	5.61KB	1.74KB
mobile (index.js)	1.50KB	0.62KB
mobile (offlineQueue.js)	3.91KB	1.35KB
mobile (pwa.js)	0.97KB	0.49KB
mobile (serviceWorker.js)	1.48KB	0.62KB
mobile (serviceWorkerSource.js)	3.41KB	1.48KB
mobile (useBreakpoint.js)	1.54KB	0.65KB
mobile (useGesture.js)	6.96KB	1.98KB
mobile (useOfflineSync.js)	1.99KB	0.72KB
mobile (usePullToRefresh.js)	2.53KB	0.85KB
mobile (useResponsive.js)	0.71KB	0.42KB
mobile (useResponsiveConfig.js)	1.36KB	0.63KB
mobile (useSpecGesture.js)	4.32KB	1.64KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	8.75KB	3.06KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	3.67KB	1.12KB
permissions (evaluator.js)	4.41KB	1.44KB
permissions (index.js)	0.91KB	0.41KB
permissions (store.js)	0.91KB	0.42KB
permissions (useFieldPermissions.js)	1.28KB	0.52KB
permissions (usePermissions.js)	1.55KB	0.71KB
plugin-ai (index.js)	15.71KB	3.79KB
plugin-calendar (index.js)	44.98KB	12.37KB
plugin-charts (index.js)	61.04KB	17.31KB
plugin-chatbot (index.js)	180.09KB	42.72KB
plugin-dashboard (index.js)	112.03KB	28.88KB
plugin-designer (index.js)	210.51KB	42.51KB
plugin-detail (index.js)	232.79KB	57.42KB
plugin-editor (index.js)	2.46KB	1.10KB
plugin-form (index.js)	112.10KB	27.10KB
plugin-gantt (index.js)	162.55KB	39.57KB
plugin-grid (index.js)	186.61KB	49.34KB
plugin-kanban (index.js)	48.30KB	13.28KB
plugin-list (index.js)	105.12KB	25.48KB
plugin-map (index.js)	16.81KB	5.24KB
plugin-markdown (index.js)	13.72KB	4.69KB
plugin-report (index.js)	40.58KB	10.58KB
plugin-timeline (index.js)	25.76KB	7.33KB
plugin-tree (index.js)	8.50KB	2.88KB
plugin-view (index.js)	84.03KB	20.55KB
providers (DataSourceProvider.js)	0.75KB	0.39KB
providers (MetadataProvider.js)	1.37KB	0.59KB
providers (ThemeProvider.js)	1.90KB	0.85KB
providers (UploadProvider.js)	11.71KB	3.53KB
providers (index.js)	0.44KB	0.22KB
providers (types.js)	0.01KB	0.04KB
react-runtime (index.js)	5.67KB	2.37KB
react (LazyPluginLoader.js)	3.77KB	1.33KB
react (SchemaRenderer.js)	19.28KB	6.38KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	1.02KB	0.55KB
react (spec-input.js)	0.20KB	0.18KB
sdui-parser (codegen.js)	4.09KB	1.74KB
sdui-parser (index.js)	4.47KB	2.03KB
sdui-parser (parse.js)	10.04KB	2.82KB
sdui-parser (types.js)	0.29KB	0.24KB
sdui-parser (validate.js)	4.69KB	1.48KB
types (ai.js)	0.20KB	0.17KB
types (api-types.js)	0.20KB	0.18KB
types (app.js)	2.87KB	0.99KB
types (base.js)	0.20KB	0.18KB
types (blocks.js)	0.20KB	0.18KB
types (complex.js)	0.20KB	0.18KB
types (crud.js)	0.20KB	0.18KB
types (data-display.js)	0.20KB	0.18KB
types (data-protocol.js)	0.20KB	0.19KB
types (data.js)	0.20KB	0.18KB
types (designer.js)	1.87KB	0.85KB
types (disclosure.js)	0.20KB	0.18KB
types (error-code.js)	1.54KB	0.88KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (http-retry.js)	4.32KB	2.02KB
types (index.js)	2.71KB	1.34KB
types (layout.js)	0.20KB	0.18KB
types (managed-by.js)	0.19KB	0.18KB
types (mobile.js)	2.59KB	1.31KB
types (navigation.js)	0.20KB	0.18KB
types (objectql.js)	0.20KB	0.18KB
types (overlay.js)	0.20KB	0.18KB
types (permissions.js)	0.20KB	0.18KB
types (plugin-scope.js)	0.20KB	0.18KB
types (record-components.js)	0.20KB	0.19KB
types (record-semantics.js)	1.28KB	0.67KB
types (registry.js)	0.20KB	0.18KB
types (reports.js)	0.20KB	0.18KB
types (spec-report.js)	5.05KB	1.93KB
types (system-fields.js)	3.33KB	1.54KB
types (theme.js)	0.20KB	0.18KB
types (ui-action.js)	3.40KB	1.71KB
types (views.js)	0.20KB	0.18KB
types (widget.js)	0.20KB	0.18KB

Size Limits

• ✅ Core packages should be < 50KB gzipped
• ✅ Component packages should be < 100KB gzipped
• ⚠️ Plugin packages should be < 150KB gzipped

[yinlianghui]

正文里两处"已另开 issue"的编号:

• packages/*/README.md 里还有 9 条 404 的站内文档链接,且链接门禁有两层原因永远看不见它们 #3603 —— packages/*/README.md 里还剩 9 条同形状的 404 站内文档链接(runner 这条是其中之一,本 PR 修掉),外加本 PR 正文写的那个两层门禁盲区的复核证据。
• packages/runner/README.md §Development Workflow 教读者写 TypeScript schema 文件,但两个 loader 都只认 JSON #3604 —— 本文件 §Development Workflow 第 1 步 "Create a schema file (JSON or TypeScript)" 与 §Metadata Loading 矛盾(两个 loader 都只认 JSON)。

两条都未认领,留给 PM 分诊;本 PR 不碰。

---

Generated by Claude Code