[zhuangjianguo]

Requested by Steedos · project thread
Fixes #395
Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么:Worker 里每个文档页面的编译模块原本打包了两份:一份给页面渲染,一份给 6 个 route handler(搜索、og、sitemap、llms 三个)。原因是这些 handler 引用的 lib/source.ts 带着每个页面的懒加载 import。现在 handler 用一个只有 frontmatter 的集合(构建时从 fumadocs-mdx 生成的文件改写),llms 用的英文 Markdown 在构建时生成;页面渲染仍从完整集合加载正文。预算步骤新增每页成本预测。
• 为什么改:每个译文页面约 170–235 KiB,Other locales, phase 2: ja to full coverage (the remaining 79 pages, seven serial PRs) #388 的 PR 3 会超出 61,440 KiB 预算,日文全量会超出 Cloudflare 64 MiB 上限。
• 风险与回滚:Worker 上传 59,173 → 38,909 KiB。预渲染输出 9,759 个文件与 main 对比,llms 正文完全一致;只有代码高亮颜色和中日文分享卡图片有差异,而 main 自己构建两次也有同样的差异。回滚即 revert 本 PR。
• 先看:apps/docs/scripts/gen-route-data.mjs 的 lightCollection(),然后看 lib/source.ts 和 lib/page-body.ts。
• 两分钟验证:看 CI 的 Worker bundle fits the size budget 摘要,新增「Per-page cost」表,每个译文页约 86 KiB,预算还能容纳约 260 页,再加一个完整语言也放得下。
• 需要你做的:无,席位落地。改动超出认领范围的部分见 Acceptance notes。

What changes

File	Change
apps/docs/scripts/gen-route-data.mjs (renamed from gen-search-data.mjs)	Still writes the search text. Now also writes .route-data/collection.ts: .source/server.ts with each page's () => import("…?collection=docs") replaced by () => body("<file>"). It throws unless every page's import was replaced. It also writes markdown.ts, the English pages' processed Markdown (remarkLLMs added at the end of the same remark chain). With --dev, collection.ts re-exports .source/server.ts instead, so next dev still sees pages added while it runs. Output moved from .search/ to .route-data/.
apps/docs/lib/source.ts	Builds the loader on @/.route-data/collection. getLLMText(page, processed?) takes the Markdown when the caller already has it.
apps/docs/lib/page-body.ts (new)	loadPageBody(page): the only module that imports the full collection.
apps/docs/app/[lang]/docs/[[...slug]]/page.tsx	Loads the body through loadPageBody, and passes the loaded _markdown to getLLMText for a translation's Copy Markdown.
apps/docs/lib/packed.ts (new)	unpack(): the gzip+base64 reader, moved out of the search route so the collection can use it too.
apps/docs/app/api/search/route.ts	Imports from .route-data/ and uses unpack(). No behaviour change.
apps/docs/package.json	build, type-check and dev (--dev) run gen-route-data.mjs.
.github/scripts/check-worker-page-cost.mjs (new)	Reads OpenNext's handler.mjs.meta.json. It prints each locale's page-module and search-text KiB per page, what one more translated page costs (the most expensive locale's per-page KiB plus 10 KiB of routing data, calibrated below), how many such pages the budget still holds, and whether one more full locale fits. It fails only when it cannot read the bundle (unreadable, no-pages). --self-test has 7 cases.
.github/workflows/ci.yml	Worker bundle fits the size budget keeps its verdict (exit "$VERDICT") and prints the projection after it, including when over budget.
tools/ci-scripts/run-self-tests.mjs	check-worker-page-cost.mjs added to SELF_TESTED.

The branch carries one -s ours merge of the landed #396 branch head so the push fast-forwards. The diff against main is only these 11 files.

Where the per-page cost went

These numbers come from the esbuild metafile of the packaged handler, with #388's PR 3 applied (61,529 KiB upload):

	KiB
page modules, page graph (chunks/ssr/content_docs_*)	19,826
page modules again, route-handler graph (chunks/content_docs_*)	19,847
everything else	~21,900

The second copy exists because route handlers are compiled as their own graph, and .source/server.ts's docsLazy map holds an import() of every page. That import() is bundled whether or not a handler calls load(). The handlers only need frontmatter, the page tree, search text and English processed Markdown, so this PR removes the copy. Highlighting and the prerendered HTML/RSC were not the cause: prerendered output is in .open-next/cache and assets, which do not count toward the upload.

Tests

Worker upload (wrangler deploy --dry-run), all builds on the same machine:

build	Total Upload	gzip
main f7e4a57 (43 ja pages)	59,173.45 KiB	10,035.53 KiB
this PR (43 ja pages)	38,907.70 KiB	7,754.59 KiB
this PR in CI (run 40880611657)	38,916.49 KiB	7,755.89 KiB
this PR, every ja page filled in (98 ja: 55 English copies)	43,699.18 KiB	8,537.71 KiB
main + full ja (measured on #394, for comparison)	66,779.77 KiB	10,276.88 KiB

Headroom with ja fully covered is 61,440 − 43,699 = 17,741 KiB. One more full locale costs about 8,421 KiB by the projection, which leaves about 9,300 KiB after it. Two more would fit too.

The projection, as the step prints it on this PR's build (CI prints the same table; its headroom is 22,523.51 KiB, leaving 14,102 KiB after one more locale):

| locale | page modules | module KiB | search KiB | KiB per page |
| en      | 98 | 4315.55 | 338.48 | 47.49 |
| zh-Hans | 98 | 5660.60 | 376.04 | 61.60 |
| zh-Hant | 98 | 5684.68 | 377.47 | 61.86 |
| ja      | 43 | 3116.37 | 148.63 | 75.93 |
A translated page costs about 85.93 KiB: ja's 75.93 KiB per page, the most of any locale, plus 10 KiB of routing data.
The budget holds 262 more such pages (22532.30 KiB of headroom).
One more fully translated locale (98 pages) would add about 8421 KiB: it fits, leaving 14111 KiB.

Calibration: going from 43 to 98 ja pages added 4,791 KiB of upload. Of that, 4,019 KiB was page modules and 238 KiB search text, so the remaining 534 KiB over 55 pages is about 10 KiB each. The projection for those 55 pages is 4,726 KiB, 1.4% under the measured growth.

• Prerendered output. I compared all 9,759 .html/.rsc/.body/.meta files under .next/server/app between main and this PR, normalizing build id and static chunk names. 9,698 are identical. Every llms.mdx body, llms-full.txt, llms.txt and sitemap.xml is identical. The 61 that differ are of two kinds, and two builds of main differ the same way (43 files on the second main build):
  • Code-highlight colours on a few pages (record-access, views, webhooks, backup here; cel, backup between the two main builds). With <script> and the colours removed, the HTML of all 9 differing pages is identical to main. It is a token-colour flicker in shiki's light theme, for example a SQL string drawn red instead of blue. It predates this PR.
  • og share-card PNGs for ja/zh pages, whose CJK glyphs come from a dynamic font fetch (Failed to load dynamic font in every build log here).
• Browser. One page per section (index, build/interface/actions, configure/permissions, cloud/storage-and-limits, deploy/docker, operate/backup, reference/cel, resources/glossary, start/community, editions/compare, use, architecture) in en and ja. Each was loaded with Playwright from opennextjs-cloudflare preview (workerd) of main and of this PR. The status, article text length and console errors (0) match on all 24. 20 full-page screenshots are byte-identical. The other 4 (operate/backup and reference/cel, in en and ja) differ in one code line's colours, the flicker above.
• Worker preview of this PR. smoke-docs.mjs --base passes. /docs/build/agents.mdx, /llms-full.txt, /llms.txt, /sitemap.xml, /og/docs/ja/build/agents/image.png and /api/search?locale=ja all answer 200.
• next dev. /ja/docs/build/agents, /docs/build/agents.mdx and /api/search answer 200, and .route-data/collection.ts re-exports the full collection.
• Gates.
  • check-search-heap.mjs: level at about 53 MB.
  • check-search-locales.mjs, check-locale-surface.mjs, check-translations.mjs, check-positioning.mjs, check-doc-samples.mjs and gen-zh-hant.mjs --check pass.
  • pnpm turbo run type-check and pnpm turbo run test (14 self-tests) pass.
  • I ran the budget step's script locally with budget 61,440 (exit 0, projection printed) and with budget 30,000 (exit 1, projection still printed).

Acceptance notes

• After landing, the post-deploy smoke check needs to be green.
• Beyond the claimed surface:
  • app/api/search/route.ts: import path and unpack() only. The generator it depends on was renamed, and the unpacking moved to lib/packed.ts so the collection shares it.
  • lib/packed.ts and lib/page-body.ts: new siblings of lib/source.ts. page-body.ts has to be a separate module from lib/source.ts, because anything the route handlers import must not reference the full collection.
  • apps/docs/package.json scripts: to run the renamed generator.
  • All three are needed for the fix.
• Unrelated finding, not fixed: shiki colours some code tokens differently from one build to the next (two builds of main differ in reference/cel and operate/backup). Readers see a string drawn red on one deploy and blue on the next.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QsR2jRsjbApbf83iyTDDXm

[objectstack-fleet]

席位核对 · ACCEPT · 2026-10-29T13:21Z · session_01QsR2jTaZ2GeyfjANMwstiw · seat repo:docs.objectos.ai#1

1. Shape. Draft PR against main f7e4a57, head 6769cd3. 11 files, +514/−142, no content files. The body says Fixes #395. Claim 6496835010, branch claude/project-thread-u7eoxi. The tree diff against main is exactly these 11 files. The history merges already-landed heads only, and the queue squashes it.
2. Surface. Four files are outside the claimed surface: app/api/search/route.ts (import path and unpack() only), the new lib/packed.ts, the new lib/page-body.ts, and the apps/docs/package.json scripts. The seat accepts them. They follow directly from the cut: search and the light collection share the packer, the page route needs the one full-collection import, and the build scripts call the renamed generator. The PR body explains each.
3. Cause and cut. Six route handlers import lib/source.ts, and the full fumadocs-mdx collection's lazy import() of every page put a second copy of every compiled page in the handlers' graph. gen-route-data.mjs rewrites .source/server.ts into a body-less collection for the handlers. It throws unless the number of page imports it replaced equals the number of pages and none are left. A fumadocs-mdx change to what it writes therefore goes red at build, not silently fat. Bodies load only in the page route, through lib/page-body.ts. The llms routes read English processed Markdown that is generated at build time, and all 98 llms.mdx bodies plus llms.txt and llms-full.txt are prerendered.
4. Seat re-run at 6769cd3.
   • Build. The local build is green, and the generator wrote search data for en 98, zh-Hans 98, zh-Hant 98, ja 43, and English Markdown for 98 pages.
   • check-search-heap. It passes: under 100 MB, and not growing.
   • check-search-locales. All 8 locales answer 200, and every locale finds its own pages by title.
5. CI, run 40880611657. build success, with all 14 self-tests passing, including the new check-worker-page-cost.
   • Worker size. Total Upload is 38,916 KiB, down from 59,172 KiB on main. That leaves 22,524 KiB of headroom under the 61,440 KiB budget.
   • Per-page projection. A translated page now costs about 86 KiB (it was about 172–235). 262 more pages fit, and one more full locale would add about 8,421 KiB, leaving 14,102 KiB.
   • Pre-merge preview smoke. It passed: 4 pages render, and search answers in all 8 locales in 0.3–0.5 s.
6. The dev's parity evidence.
   • Of 9,759 prerendered files, 9,698 are identical, including every llms body and the sitemap. The 61 that differ are shiki token colours and CJK og PNGs, which also differ between two builds of main.
   • 24 pages were browsed in en and ja on the workerd preview. 20 screenshots are byte-identical, and the other 4 differ only in code-line colour.
   • A full-ja simulation measured 43,699 KiB.
7. Landing. Tier none. It lands through the merge queue under the standing go-ahead, serially, and the post-deploy smoke check must be green. Other locales, phase 2: ja to full coverage (the remaining 79 pages, seven serial PRs) #388 then resumes with PR 3.