docs(examples): 给 console-starter 补 README

[yinlianghui]

Fixes #3520

背景

examples/ 下四个目录里,console-starter 是唯一没有 README 的那个(git ls-tree 只有 10 个文件,全是配置与 src/)。而 PR #3506 刚把 content/docs/guide/objectos-integration.mdx 的 "Example: CRM Application" 死链改指 https://github.com/objectstack-ai/objectui/tree/main/examples/console-starter —— 读者点过去落到一个没有任何说明的裸目录。

本 PR 只新增 examples/console-starter/README.md 一个文件。内容全部来自实测(读 src/ 与配置、真起 dev server、真用无头浏览器打开),不写推断。

README 回答的四问

1. 它是什么 —— 连真实 ObjectStack 后端的 console 脚手架。逐条对着源码点名:src/App.tsx 用 @object-ui/app-shell 的 ConsoleShell / AuthenticatedRoute / ConnectedShell / RootRedirect / SystemRedirect / Default* 页 / DefaultAppContent 拼出整棵路由树;鉴权是 @object-ui/auth 的 AuthProvider 指向 ${VITE_SERVER_URL}/api/v1/auth;src/main.tsx 以 side-effect import 注册十个视图插件,并从 /api/v1/i18n/translations/:lang 取翻译。每个描述都能在 packages/app-shell/src/console/ConsoleShell.tsx 的对应导出上核对。

2. 它不是什么 —— 这一节是 #3509 那条边界的落地。#3509 明确因为 console-starter 不演示关系建模,才没有把 "Build multi-object apps with relationships" 的链接指过来。README 直说:本目录十个文件里没有任何一处声明对象、字段或关系,它们全在服务端;要看建模去 schema-catalog 和 content/docs/fields/lookup.mdx。另外两条边界同样点明:数据层硬绑 ObjectStackAdapter(自带后端请看 byo-backend-console),以及没有 mock/离线模式。

3. 怎么跑 —— 实测结论,不是从 package.json 抄命令:

• pnpm -w build 是硬前置,不是套话。vite.config.ts 把 24 个 @object-ui/* 别名指到 packages/*/src,但这些源码又 import 了 5 个不在别名表、也不在本 example package.json 里的工作区包(mobile、providers、sdui-parser、plugin-editor、react-runtime)。它们只能走 node 解析落到 packages/*/dist,而 dist 只有构建后才存在。
• 端口:vite.config.ts 没有设 server.port(对比 byo-backend-console 设了 5174),所以是 Vite 默认 5173。
• 后端:VITE_SERVER_URL 是唯一要紧的开关(adapter / auth / i18n / action 端点都挂在它上面),.env.development = http://localhost:3000,.env.production = https://demo.objectstack.ai,留空即同源。需要本地后端时指向仓库自带的 e2e/live/ci/start-backend.sh(它起真的 objectstack dev,4010 端口,seeded admin),并如实注明那是 CI lane 的脚本、会先拉 showcase 元数据并 npm install。
• VITE_USE_MOCK_SERVER 在两个 .env 里都有,但全仓没有任何源码读它(仅 apps/console/vercel.json 的构建命令里出现)。README 用一句话说清"它是从 apps/console 抄过来的、没有 mock 模式",免得读者去翻它。另见下方"越界发现"。

4. 与另外三个 example 的分工 —— 照 examples/README.md 的口径给四行短版并链回总目录,不重复它的表格。

验证(先预测,后执行)

预测:测试不动。 README-only 的 diff,没有任何测试引用 examples/console-starter(grep -rln 在 scripts/、packages/、apps/ 的 *.test.ts* 里零命中);check-doc-links 的扫描面只有 content/docs/,本文件不在其中。

结果与预测一致:

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

204 与 #3509 记录的基线逐个相同 —— 没有 verdict 移动,也没有新增覆盖。

$ node scripts/check-doc-links.mjs
Docs links are valid.

$ node scripts/check-control-bytes.mjs     # 文件已 git add 后重跑
✅  check-control-bytes: OK (scanned 3691 tracked text file(s); skipped 85 binary).

(3690 → 3691,证明新文件确实进了扫描面。另对该文件单独 grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]',无命中。)

链接自查 —— 这一条要说清证据来源。 check-doc-links.mjs 只走 content/docs/,不会校验本文件里的任何链接,所以门禁绿不代表链接对。逐条按存在性自己验:脚本抽出 README 里 14 条相对链接、fs.existsSync 逐个解析,14 relative links checked, 0 missing。这就是本文件链接正确性的全部证据。

真跑过 —— 而且第一次是红的。 跑法与结果:

1. 只 pnpm install 就 pnpm dev(自选空闲端口 5197,--strictPort):Vite 350ms 起来,但 dep scan 报 5 个 @object-ui/* 无法解析;无头 Chromium 打开后 #root 完全为空,body 无文字,多个 500。
2. 按上面第 3 点补 pnpm --filter ... build 把那 5 个包(及其依赖)构建出来后重启:#root 渲染出品牌加载屏,body 文字为 ObjectOS / Initializing application... / Connecting to data source / Loading configuration / Preparing workspace。
3. 因为 :3000 上没有后端,控制台是一片 ERR_CONNECTION_REFUSED,页面停在该加载屏(adapter 永远连不上,底下的路由不会挂载);同一状态下 /login 反而完整渲染(登录页不在 ConnectedShell 之下),只是登不进去。

README 的"Without a backend"一节写的就是第 3 步的观察。第 1 步的红不是缺陷,是我漏了 examples/README.md 与根 README.md 早已写明的 pnpm -w build —— 它反过来成了 README 里"根构建不是可选项"那一段的实据。

服务已拆。 自起的 dev server 按记下的 PID 关闭(lsof -tiTCP:5197 确认端口已释放),临时 probe 脚本已删,工作树只剩这一个新文件。

越界发现(只报不改,文件面严格限于新增的 README)

见下方 issue 评论/新单:content/docs/guide/deployment.md 记的 VITE_USE_MOCK_SERVER、VITE_API_URL 两个变量在全仓无任何源码读取(真实变量是 VITE_SERVER_URL);以及本 example 的 vite 别名表与 package.json 覆盖不全,按 vite.config.ts 注释"发布后可以删掉别名"去 fork 会直接坏掉。均按仓库惯例另立 issue,不在本 PR 顺手改。

范围

• 无 changeset:example README,沿用 docs(examples): 修复 hello-world README 指向已删除示例的两条死链 #3495(hello-world README)的先例。
• 未触碰 content/docs/releases/。
• 未触碰 examples/README.md(它写着"Each exposes its own dev server port (see its README)",而 console-starter 并未声明端口 —— 只报不改)。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt

---

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 2:39am

[yinlianghui]

越界发现已按仓库惯例另立单,本 PR 未触碰任何相关文件:

• 文档站教读者配 VITE_API_URL / VITE_USE_MOCK_SERVER,两个变量全仓无任何源码读取 #3527 — content/docs/guide/deployment.md 的环境变量表与 console.md:93-95 教读者配 VITE_API_URL / VITE_USE_MOCK_SERVER,两者在全仓源码里 0 命中;真正生效的 VITE_SERVER_URL 在 content/ 下反而 0 次出现。会让读者配错且无任何报错,未打标签,留给 PM 分诊。
• console-starter 的 vite 别名表漏了 5 个源码实际 import 的工作区包,未先构建就 pnpm dev 得到白屏 #3528 — examples/console-starter/vite.config.ts 的 24 条别名漏了 5 个源码实际 import 的工作区包,跳过 pnpm -w build 直接 pnpm dev 得到纯白屏 + 无文案(实测 #root innerHTML 长度 0,6 条 500)。按文档顺序走不会踩到,故标 finding、不排队。

另一条只报不改、未单独立单的事实:examples/README.md 写着 "Each exposes its own dev server port (see its README)",而 examples/console-starter/vite.config.ts 没有设 server.port(对比 byo-backend-console 设了 5174),实际是 Vite 默认 5173。本 PR 的 README 已如实写明 5173,examples/README.md 那句话本身保持原样。

立单时 list_issues 一直 API rate limit already exceeded(共享身份、多 agent 并行,约 20 分钟冷却未恢复),两单都未能完成 open issues 查重,已在各自正文里注明,若有同源单请 race-close。

---

Generated by Claude Code

---

Generated by Claude Code