Skip to content

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

Merged
yinlianghui merged 1 commit into
mainfrom
claude/issue-3576-runner-readme-fictions
Aug 7, 2026
Merged

docs(runner): 删掉 README 两处虚构能力面(createRunner/runner.config.js),修正 404 文档链接 (#3576)#3602
yinlianghui merged 1 commit into
mainfrom
claude/issue-3576-runner-readme-fictions

Conversation

@yinlianghui

Copy link
Copy Markdown
Collaborator

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 installpnpm --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.jsonpages 里列了 runner,content/docs/meta.jsonpages 里列了 utilities。同一 README 底部 ## Links 的 Documentation 一条本来就是这个 URL,package.jsonhomepage 也是 —— 现在三处一致。

顺带把标题 ## 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.mjsSCAN_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(filesREADME.md),但改的是纯错误叙述,没有版本语义。


Generated by Claude Code

`createRunner()` / `runner.config.js` 全仓零代码引用,包也没有任何库入口
(main/module/exports/types 全无),按 #3533 的口径清除;`/docs/runner`
是死路由,改成实际存在的 `/docs/utilities/runner`。
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt
@vercel

vercelBot commented Aug 7, 2026

Copy link
Copy Markdown

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

1 Skipped Deployment
ProjectDeploymentActionsUpdated (UTC)
objectuiIgnoredIgnoredAug 7, 2026 3:40pm

Request Review

@github-actions

Copy link
Copy Markdown
Contributor

✅ Console Performance Budget

MetricValueBudget
Main entry (gzip)28.1 KB350 KB
Entry fileindex-CVz6ARkO.js
StatusPASS

📦 Bundle Size Report

PackageSizeGzipped
app-shell (index.js)8.66KB3.13KB
app-shell (runtime-config.js)7.42KB2.32KB
app-shell (types.js)0.01KB0.04KB
app-shell (urlParams.js)7.57KB2.97KB
auth (AuthContext.js)0.31KB0.24KB
auth (AuthGuard.js)1.17KB0.53KB
auth (AuthProvider.js)22.10KB4.37KB
auth (AuthShell.js)3.49KB1.40KB
auth (ForgotPasswordForm.js)12.21KB3.45KB
auth (LoginForm.js)18.13KB5.39KB
auth (PreviewBanner.js)0.90KB0.50KB
auth (RegisterForm.js)6.64KB2.21KB
auth (SocialSignInButtons.js)9.60KB3.89KB
auth (UserMenu.js)3.40KB1.22KB
auth (auth-gate-events.js)1.29KB0.66KB
auth (authStyles.js)5.04KB1.72KB
auth (createAuthClient.js)35.76KB9.11KB
auth (createAuthenticatedFetch.js)4.37KB1.69KB
auth (index.js)2.35KB1.07KB
auth (org-roles.js)6.66KB2.78KB
auth (phone-identifier.js)1.11KB0.66KB
auth (types.js)0.59KB0.35KB
auth (useAuth.js)4.91KB0.87KB
auth (useIsWorkspaceAdmin.js)1.61KB0.85KB
collaboration (CommentThread.js)26.07KB7.56KB
collaboration (LiveCursors.js)3.17KB1.27KB
collaboration (PresenceAvatars.js)6.49KB2.64KB
collaboration (PresenceProvider.js)2.79KB1.13KB
collaboration (index.js)1.65KB0.73KB
collaboration (useCollaborationTranslation.js)6.05KB2.52KB
collaboration (useCommentSearch.js)1.98KB0.88KB
collaboration (useConflictResolution.js)7.75KB1.86KB
collaboration (useMentionNotifications.js)1.81KB0.68KB
collaboration (usePresence.js)6.33KB1.84KB
collaboration (useRealtimeSubscription.js)7.91KB2.01KB
components (index.js)480.72KB105.64KB
core (index.js)2.96KB1.13KB
create-plugin (index.js)9.28KB2.98KB
data-objectstack (index.js)137.51KB35.11KB
fields (index.js)230.87KB56.83KB
i18n (LocalizationContext.js)1.76KB0.96KB
i18n (currency.js)1.22KB0.64KB
i18n (i18n.js)4.32KB1.77KB
i18n (index.js)2.65KB1.06KB
i18n (pickLocalized.js)1.70KB0.83KB
i18n (provider.js)9.48KB3.27KB
i18n (useObjectLabel.js)26.14KB6.07KB
i18n (useSafeTranslation.js)4.52KB1.96KB
layout (index.js)38.53KB10.71KB
mobile (MobileProvider.js)0.92KB0.49KB
mobile (ResponsiveContainer.js)0.94KB0.38KB
mobile (breakpoints.js)1.51KB0.70KB
mobile (createOfflineDataSource.js)5.61KB1.74KB
mobile (index.js)1.50KB0.62KB
mobile (offlineQueue.js)3.91KB1.35KB
mobile (pwa.js)0.97KB0.49KB
mobile (serviceWorker.js)1.48KB0.62KB
mobile (serviceWorkerSource.js)3.41KB1.48KB
mobile (useBreakpoint.js)1.54KB0.65KB
mobile (useGesture.js)6.96KB1.98KB
mobile (useOfflineSync.js)1.99KB0.72KB
mobile (usePullToRefresh.js)2.53KB0.85KB
mobile (useResponsive.js)0.71KB0.42KB
mobile (useResponsiveConfig.js)1.36KB0.63KB
mobile (useSpecGesture.js)4.32KB1.64KB
mobile (useTouchTarget.js)1.01KB0.54KB
permissions (MePermissionsProvider.js)8.75KB3.06KB
permissions (PermissionContext.js)0.31KB0.25KB
permissions (PermissionGuard.js)0.89KB0.45KB
permissions (PermissionProvider.js)3.67KB1.12KB
permissions (evaluator.js)4.41KB1.44KB
permissions (index.js)0.91KB0.41KB
permissions (store.js)0.91KB0.42KB
permissions (useFieldPermissions.js)1.28KB0.52KB
permissions (usePermissions.js)1.55KB0.71KB
plugin-ai (index.js)15.71KB3.79KB
plugin-calendar (index.js)44.98KB12.37KB
plugin-charts (index.js)61.04KB17.31KB
plugin-chatbot (index.js)180.09KB42.72KB
plugin-dashboard (index.js)112.03KB28.88KB
plugin-designer (index.js)210.51KB42.51KB
plugin-detail (index.js)232.79KB57.42KB
plugin-editor (index.js)2.46KB1.10KB
plugin-form (index.js)112.10KB27.10KB
plugin-gantt (index.js)162.55KB39.57KB
plugin-grid (index.js)186.61KB49.34KB
plugin-kanban (index.js)48.30KB13.28KB
plugin-list (index.js)105.12KB25.48KB
plugin-map (index.js)16.81KB5.24KB
plugin-markdown (index.js)13.72KB4.69KB
plugin-report (index.js)40.58KB10.58KB
plugin-timeline (index.js)25.76KB7.33KB
plugin-tree (index.js)8.50KB2.88KB
plugin-view (index.js)84.03KB20.55KB
providers (DataSourceProvider.js)0.75KB0.39KB
providers (MetadataProvider.js)1.37KB0.59KB
providers (ThemeProvider.js)1.90KB0.85KB
providers (UploadProvider.js)11.71KB3.53KB
providers (index.js)0.44KB0.22KB
providers (types.js)0.01KB0.04KB
react-runtime (index.js)5.67KB2.37KB
react (LazyPluginLoader.js)3.77KB1.33KB
react (SchemaRenderer.js)19.28KB6.38KB
react (data-invalidation.js)5.05KB2.08KB
react (index.js)1.02KB0.55KB
react (spec-input.js)0.20KB0.18KB
sdui-parser (codegen.js)4.09KB1.74KB
sdui-parser (index.js)4.47KB2.03KB
sdui-parser (parse.js)10.04KB2.82KB
sdui-parser (types.js)0.29KB0.24KB
sdui-parser (validate.js)4.69KB1.48KB
types (ai.js)0.20KB0.17KB
types (api-types.js)0.20KB0.18KB
types (app.js)2.87KB0.99KB
types (base.js)0.20KB0.18KB
types (blocks.js)0.20KB0.18KB
types (complex.js)0.20KB0.18KB
types (crud.js)0.20KB0.18KB
types (data-display.js)0.20KB0.18KB
types (data-protocol.js)0.20KB0.19KB
types (data.js)0.20KB0.18KB
types (designer.js)1.87KB0.85KB
types (disclosure.js)0.20KB0.18KB
types (error-code.js)1.54KB0.88KB
types (feedback.js)0.20KB0.18KB
types (field-types.js)0.20KB0.18KB
types (form.js)0.20KB0.18KB
types (http-retry.js)4.32KB2.02KB
types (index.js)2.71KB1.34KB
types (layout.js)0.20KB0.18KB
types (managed-by.js)0.19KB0.18KB
types (mobile.js)2.59KB1.31KB
types (navigation.js)0.20KB0.18KB
types (objectql.js)0.20KB0.18KB
types (overlay.js)0.20KB0.18KB
types (permissions.js)0.20KB0.18KB
types (plugin-scope.js)0.20KB0.18KB
types (record-components.js)0.20KB0.19KB
types (record-semantics.js)1.28KB0.67KB
types (registry.js)0.20KB0.18KB
types (reports.js)0.20KB0.18KB
types (spec-report.js)5.05KB1.93KB
types (system-fields.js)3.33KB1.54KB
types (theme.js)0.20KB0.18KB
types (ui-action.js)3.40KB1.71KB
types (views.js)0.20KB0.18KB
types (widget.js)0.20KB0.18KB

Size Limits

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

@yinlianghuiClaude

Copy link
Copy Markdown
CollaboratorAuthor

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

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


Generated by Claude Code

@yinlianghui
yinlianghui marked this pull request as ready for review August 7, 2026 15:44
@yinlianghui
yinlianghui added this pull request to the merge queueAug 7, 2026
Merged via the queue into main with commit 622c230Aug 7, 2026
7 checks passed
@yinlianghui
yinlianghui deleted the claude/issue-3576-runner-readme-fictions branch August 7, 2026 15:45
akarma-synetal pushed a commit to akarma-synetal/objectui that referenced this pull request Aug 10, 2026
…ion (objectstack-ai#3577) (objectstack-ai#3616)
三类结构性虚构,均对 origin/main 逐条复核后处理。范围是整页 8 处锚点,
不是正文列的 3 处 —— 只修 Directory Structure 会让全页继续自相矛盾。
1. 幽灵目录。`packages/runner/src` 下实测只有 App.tsx / LayoutRenderer.tsx /
main.tsx / index.css / lib/ / 测试文件,没有 `schemas/`、没有 `components/`,
包根也没有 `public/`。按 objectstack-ai#3534/objectstack-ai#3539 先例(删手抄目录树,指真源)整块删掉
Directory Structure,换成一段实测过的 prose,并把承重信息落在唯一真实的
元数据目录 `src/app-data/` 上 —— 它由 `.gitignore` 排除、新检出下不存在,
布局与解析顺序由本页自己的 Metadata Loading 一节(objectstack-ai#3581 补)承接。
其余 5 处 `src/schemas/` 引用(Use Cases 两处、Add Custom Schemas、
Best Practices 目录树)一并按 Metadata Loading 的真实契约改写为
`src/app-data/pages/*.json`;页文档形状取 App.tsx 兜底页的
`{ type: 'page', title, body: [] }`,与本页 Metadata Loading 表格里
「the page document (PageNodeSchema)」一致。
2. 「内置示例 schema」。这个包一个 schema 文件都不带:承载它们的
`src/app-data/` 在 `packages/runner/.gitignore:1` 里,缺该目录时
LocalBundleLoader 三个 `import.meta.glob` 编译为 `{}`,`/` 渲染内置兜底
`No index page found.`。What's Included 下那节列七类「Runner 包含的示例
schema」整节改写为读者实际要做的事(往 `src/app-data/` 放 JSON,或用
`?api=` 指后端);下方 `## Example Schemas` 改题为 Schemas to Start From,
并说明这些例子活在文档里、不在包里。
3. Package Information。`Version: 0.3.1` 直接删除,不改成 17.3.0 ——
`@object-ui/runner` 在 `.changeset/config.json` 的 fixed 组里随 39 包同发,
手抄版本号必然再次漂移(分诊亦持此意见);当前版本改为指向 npm 页。
`Type: Application (not published to npm)` 与实测相反:package.json 是
`"private": false` + `publishConfig.access: "public"`,registry 上
`dist-tags.latest = 17.3.0`。改为不随版本漂移的措辞:已发布,但它是应用
不是库 —— package.json 不声明 main/module/exports/types,没有可 import 的
东西(与 PR objectstack-ai#3602 刚给 README 定下的说法一致)。
`src/components/` 保留一处 —— Add Custom Components 的 `// src/components/
MyComponent.tsx`。那是让读者自己建的文件(下方注册片段的相对 import 必须与它
对齐),已在上一句明写「包里不带组件,这个目录你自己加」,不再是「它存在」的
断言。
越界发现另行开单,不在本 PR 修:Features 的「All official plugins included」、
Best Practices 的环境变量小节(objectstack-ai#3538 删了 Environment Variables 整节却漏了它)、
Add Custom Routes 的 react-router-dom(runner 不依赖它,路由是手写
history.pushState)。objectstack-ai#3604 是 README 的另一件事,未触碰。
Fixesobjectstack-ai#3577
Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt
Co-authored-by: Claude <noreply@anthropic.com>
akarma-synetal pushed a commit to akarma-synetal/objectui that referenced this pull request Aug 10, 2026
…bjectstack-ai#3604) (objectstack-ai#3621)
第 1 步「Create a schema file (JSON or TypeScript)」与本文件自己的
§Metadata Loading 直接矛盾:runner 没有任何路径能加载 TypeScript 写的
schema —— LocalBundleLoader 的三个 import.meta.glob 全是 `.json`
(MetadataLoader.ts:26-28),NetworkLoader 只 fetch 固定的 `.json` 路径
并直接 `res.json()`(同文件 89、101 行)。按 objectstack-ai#3533 的口径(文档不许描述
实现里不存在的能力)改写成 JSON 的两条真实路线,并点名 `src/app-data/`
是 git-ignored、新检出下不存在、仓里没有任何脚本会创建它 —— 这正是照旧
文本操作的读者下一步会撞上的坑(每次加载返回 null,页面渲染成 404)。
第 3 步「changes reload automatically」按 loader 分路限定而非删除:
`src/app-data/` 下的 JSON 在 Vite 的 module graph 里,改动不需要重启 dev
server;`?api=` 那条 Vite 根本看不见后端。这里刻意没有断言浏览器会自动
刷新 —— App.tsx 只导出组件,是 react-refresh 的边界,更新可能被
保状态的重渲染吸收,而这一点脱离实跑无法从代码确认;写不确定的机制
断言正是本 issue 要清的那类虚构。改成「视图仍是旧文档就刷新页面」,
两种机制下都成立,且对读者可操作。
无 changeset:包 README 的文档修正,与 objectstack-ai#3602(同一文件,同样只改 README)
先例一致;ci.yml / lint.yml 对 `**/*.md` 走 paths-ignore。
Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt
Co-authored-by: Claude <noreply@anthropic.com>
akarma-synetal pushed a commit to akarma-synetal/objectui that referenced this pull request Aug 10, 2026
…stack-ai#3644)
`packages/runner/README.md` 两处把预装插件写成开放集合,实测预装的恰好是
kanban + charts 两个:`packages/runner/package.json` 的 dependencies 里
`plugin-*` 只有 `@object-ui/plugin-charts` 与 `@object-ui/plugin-kanban`,
`packages/runner/src/App.tsx:14-15` 也只有这两行注册 import。
- §Features:`(Kanban, Charts, etc.)` 已穷举全部两个却仍缀 `etc.`,读起来是
「还有更多没列」。去掉 `etc.` 并闭合为实测集合;一并去掉 `popular` ——
集合闭合后「popular plugins」仍读作「从更大集合里挑的几个热门」,会把刚
合上的口子重新撑开。
- §Pre-installed Plugins:非插件的加粗行「**Additional plugins can be added
as needed**」被排在「comes with these plugins pre-configured」引出的列表
里、且与前两条同样加粗,形状上成了第三个预装项。把它移出列表,降为列表
下方的说明句,并按实测写清加插件的真实代价(改 `package.json` 依赖、
`src/App.tsx` 注册 import,以及现有两个插件在 `vite.config.ts` 别名表和
`src/index.css` `@source` 里各有的条目)后重新构建 —— runner 没有运行时
插件安装机制。
无 changeset:包 README 的事实订正,不改任何发布产物或公开 API,沿用
objectstack-ai#3602 / objectstack-ai#3621 / objectstack-ai#3634 的先例。
Fixesobjectstack-ai#3632
Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt
Co-authored-by: Claude <noreply@anthropic.com>
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentationImprovements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

packages/runner/README.md 记载了两个不存在的能力(createRunner() 程序化 API、runner.config.js),外加一条 404 的文档链接

2 participants

@yinlianghui@claude