fix(spec): docs-gen 按 JSDoc 原有行布局渲染模块描述,并让裸路径改写跳过已成型链接 (#5553, #6136)

[os-zhuang]

Fixes #5553
Fixes #6136

两单同落 packages/spec/scripts/lib/file-description.ts(#5059/PR #6134 今日新建),同一条渲染链上的两条互不相干的缺陷,合并为一个 PR —— 分开派会各付一次 content/docs/references/** 重生成并互埋 diff。

前提复核(先于实现,对 current origin/main)

两单正文都早于 #6134 的抽取,代码形状已移位,故逐条复核:

• docs-gen: 无标题的 {@link ../x.zod.ts} 被渲染成「链接套链接」—— 2 张已发布参考页正文里能直接看到 #6136 —— 完全成立。 grep -rn '\[\.\./\[' content/docs/references/ 在 main 上仍返回 automation/etl.mdx:54 与 integration/connector.mdx:102,两条正文与 issue 引用逐字一致。
• docs-gen: 模块 JSDoc 按行拆成段落,跨行的行内代码跨度被切断 —— 5 张参考页正文露出裸反引号和 \{ 转义痕迹 #5553 —— 成立,但受害面从 5 页缩到 4 页。 按行段落切分与无差别花括号转义两处代码原封不动仍在。issue 点名的 5 张页面里,system/doc 已不在其中:fix(spec): 参考页开篇只认「不属于任何符号」的模块级 doc block (#5059) #6134 的取块规则发现该文件的 header 紧跟 export const DocSchema(即它记录的是那个符号),已停止发布 —— 属于前提在派发前自然消解,不是本 PR 的功劳。其余 4 张(automation/flow-function、security/explain、shared/expression、system/settings-client)按段落计的未配对反引号 8 处,复现无误。

⛔ #6134 的取块规则一字未动:185 个带模块头的源文件修改前后都渲染出描述,无一页新增或丢失开篇描述(#6134 的验收标准,已作为语料 pin 固化)。

改法

两条缺陷根因同形:变换施加的粒度错了。

#5553。 渲染器丢掉全部空行、把剩下的每一源码行用 \n\n 连接 —— 即宣布每一源码行自成一段。任何合法跨行的构造都被段落边界切断,而行内代码跨度不能跨空行,两边反引号因此当字面量渲染。同一段还对全文无差别转义花括号(含代码内部,那里反斜杠不是转义符而是读者看得见的字符)。

改法是不再重写布局:去掉 * 边栏后保持原样,段落切分交还 markdown 自身。issue 提的「连续非空行用空格连接」在语义上正是 markdown 的软换行规则,但字面照做会摧毁列表 —— 185 个带描述的源文件里 85 个写了列表。转义与链接解析收窄到正文:围栏/缩进代码块原样保留,正文内由 tokenizer 把行内代码跨度挡在外面。

#6136。 无标题 {@link 路径} 会产出一条 markdown 链接,而它的链接文本恰好就是那条路径本身;紧随其后的裸路径改写器在整串上再跑一次,匹配到链接文本里的路径,又把它包了一层。前后瞻表达不了「不在链接内部」,故改为按 token 施加、排除已成型链接。裸路径正则本身一字未改,修复完全来自 tokenize —— 括号内路径等既有渲染因此零附带变化。

一处刻意不照抄源码布局:缩进(4 空格)代码块改用围栏输出。 MDX 为了让缩进用于排布 JSX,取消了 CommonMark 的缩进代码块,所以这种块会以正文身份进入编译器。data/date-macros、data/context-tokens 的占位符示例正是这样写的且几乎全是花括号 —— 保持缩进则 Could not parse expression with acorn 编译失败(第一版实现实测踩到,由全量 MDX 编译检查逮住);改成转义则读者在本该是代码的地方看到 \{,正是 #5553 要修的那条。目标方言里代码块只有围栏一种拼法。

反向验证(先定方向,再逐条恢复;红集必须不相交)

恢复的缺陷	预测	实测变红
A #5553 按行切段	结构类 pin + 语料「切断跨度」	5 条,全部在 #5553 组
B #5553 无差别转义	代码跨度/围栏/缩进 pin + 语料「代码内反斜杠」	5 条,全部在 #5553 组
C #6136 改写器跑整串	2 条 {@link} pin + 语料「链接套链接」	3 条,全部在 #6136 组

(A∪B) ∩ C = ∅ —— 这就是「两条独立缺陷、不是一条」的证据,与 #6136 立单者在 #5059 报告里的论断一致。

一处预测落空,如实记录:我预测 A 会让「连续 @see 保持独立块」变红,实际为绿 —— 把每行切成独立段落恰好也把那几行分开了,是巧合而非该 pin 失效。

受影响的参考页(169 张)与归属

#6136 —— 2 张,各一行「另见」由「链接套链接」恢复为单个可点链接:

• automation/etl.mdx:54 → See also: [../integration/connector.zod.ts](/docs/references/integration/connector) for the Enterprise Connector layer
• integration/connector.mdx:102 → See also: [../automation/etl.zod.ts](/docs/references/automation/etl) for the ETL Pipeline layer (data engineering)

#5553 —— 全部 169 张(上面 2 张同时含 #5553 改动)。按变化种类计:

• 被切断的行内代码跨度复原(4 张):automation/flow-function、security/explain、shared/expression、system/settings-client —— 每张 2 处→0。
• 代码内 \{ 反斜杠残留清零(33 张):全语料 296 → 0;正文中合法转义的 28 处保留不动。
• 围栏代码块恢复(32 张):@example 样例此前被拆成每行一段并逐行转义,现为真正的代码块。
• 缩进恢复(47 张):嵌套列表恢复层级。
• 缩进块改围栏(2 张):data/date-macros、data/context-tokens。
• 其余为段落重新合并与列表由「松」变「紧」。

169 张页面完整清单(按 category)

• ai (8): conversation, embedding, knowledge-document, knowledge-source, mcp, model-registry, skill, usage
• api (23): analytics, auth, auth-endpoints, automation-api, batch, discovery, dispatcher, documentation, endpoint, errors, events, export, http-cache, metadata, odata, package-api, plugin-rest-api, query-adapter, realtime-shared, rest-server, storage, versioning, websocket
• automation (13): bpmn-interop, builtin-node-config, control-flow, etl, execution, flow, flow-function, io-node-config, node-executor, schemaless-node-config, state-machine, time-relative-trigger, webhook
• cloud (10): app-store, developer-portal, environment, environment-artifact, environment-package, marketplace, marketplace-admin, package, package-version, tenant
• data (22): analytics, context-tokens, data-engine, datasource, date-macros, document, driver, driver-common, driver-memory, driver-mongo, driver-nosql, driver-sql, external-catalog, external-lookup, feed, field-value, filter, hook, query, seed, seed-loader, validation
• identity (5): eval-user, identity, organization, position, scim
• integration (1): connector
• kernel (28): cli-extension, cluster, context, dependency-resolution, events-bus, events-core, events-dlq, events-handlers, events-integrations, events-queue, execution-context, metadata-customization, metadata-plugin, metadata-protection, package-artifact, package-registry, package-upgrade, plugin-capability, plugin-lifecycle-advanced, plugin-loading, plugin-registry, plugin-security, plugin-security-advanced, plugin-structure, plugin-validator, plugin-versioning, service-registry, startup-orchestrator
• security (4): explain, permission, rls, sharing
• shared (6): branded-types, expression, http, identifiers, mapping, protection
• studio (3): flow-builder, object-designer, plugin
• system (33): app-install, auth-config, book, cache, change-management, collaboration, core-services, deploy-bundle, disaster-recovery, email-config, email-template, encryption, environment-artifact, http-server, incident-response, job, logging, message-queue, metadata-persistence, metrics, migration, object-storage, registry-config, search-engine, security-context, settings-client, settings-manifest, stack-server, supplier-security, tenant, tracing, training, worker
• ui (13): action, action-params, app, bulk-action, chart, dataset, i18n, notification, page, sharing, theme, view, widget

顺带修好的邻居门(必须,不是顺手)

scripts/escape-mdx.test.ts 的 #5452 语料门断言「行内代码跨度里花括号必须配平」,但按行提取跨度 —— 这只在模块 JSDoc 把每行当独立段落时才碰巧成立。本 PR 恢复行布局后跨度可以跨行,该门只看到开头半截,把正常跨行的跨度读成不配平并变红。改为按段落提取(空行仍是硬边界,因为代码跨度不能跨空行),并先把围栏块置空。#5452 自身的缺陷形态(同一行内被切成半对)报告方式不变,已用合成样例复核仍会报出。

验证

• pnpm --filter @objectstack/spec test —— 330 files / 8435 tests 全绿(pin 由 14 条扩到 28 条 + 2 条新语料门)。
• pnpm --filter @objectstack/spec typecheck —— 绿。
• check:docs 232 files in sync ✅ / check:generated 10 artifacts up to date ✅ / check:api-surface unchanged ✅。
• eslint 三个改动文件 —— 绿;check:nul-bytes、check:doc-authoring、check:empty-changeset —— 绿。
• 全量 216 张参考页经 @mdx-js/mdx 编译通过(216/216);已核对 origin/main 同样为绿,故这是「未引入回归」而非「修好了原有失败」。

范围

content/docs/references/** 重生成独立成 commit。未触碰 build-docs.ts(#5853 下轮)、lib/format-type.ts(#5340)、lib/zod-graph.ts、build-schemas.ts(#5371)、任何 *.zod.ts 源码、content/docs/releases/。已加 changeset(@objectstack/spec: patch),与两个同类邻居 PR(#5550、#6134)一致。

纯展示层,无运行时/协议/导出面语义变化。

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 7, 2026 12:31pm

[github-actions]

📓 Docs Drift Check

No hand-written docs reference the 0 changed package(s). ✅

[os-zhuang]

PM 验收：ACCEPT（内容），但暂不 ready —— 卡在一条排序约束上，理由见下。

内容验收依据取自 GitHub 侧读数：

• CI：head ac1e9301f 共 25 个 check，全部 success/skipped，零 failure。逐一核对门禁项：ESLint success、TypeScript Type Check success、Build Docs success（169 页重生成最该盯的一格）、Check Changeset success、Spec property liveness success、两次 No other open PR may claim the same issue 均 success（一个 PR 认领两单确属合规）。
• Changeset：本单发布东西（content/docs/references/** 是 @objectstack/spec 的发布面），故带 @objectstack/spec: patch changeset、skip-changeset 正确缺席。符合 Check Changeset 的失败文案把「空 changeset」推荐为出路 —— 而那正是 #4898 静默卡死发布的输入 #5292 起的三选一规则，且与同类邻居 fix(spec): docs-gen 把嵌套花括号整对包进行内代码,不再切成半对 (#5452) #5550、fix(spec): 参考页开篇只认「不属于任何符号」的模块级 doc block (#5059) #6134 一致。
• fix(spec): 参考页开篇只认「不属于任何符号」的模块级 doc block (#5059) #6134 验收标准仍成立：185 个带模块头的源文件修改前后都渲染出描述，无一页新增或丢失开篇描述，并已固化为语料 pin —— 这正是我在派发令里要求复核的那一格。

⏸ 为什么现在不 ready

#6211（#5340，长枚举省略）已在合并队列中，且同样重生成 content/docs/references/**（42 页 / 144 行）。 本 PR 重生成 169 页，两者生成页重叠。此刻 ready + auto-merge 会让两个 PR 在队列里相遇——风险不是「冲突」（那反而是好结果，会响亮失败），而是两边各自从不同源状态生成、却文本上合得干净，落地一棵陈旧的生成树。

所以按 #4675 的四步重建走，等 #6211 落 main 后再放行：merge main → checkout 生成物 → 先提交 merge → 整体重生成。届时我会唤回本单的 dev 补这一轮，CI 重跑后再 ready。

三项做得对、我希望成为本车道常规的

1. 反向验证的红集不相交即证据：A∪B（docs-gen: 模块 JSDoc 按行拆成段落,跨行的行内代码跨度被切断 —— 5 张参考页正文露出裸反引号和 \{ 转义痕迹 #5553）与 C（docs-gen: 无标题的 {@link ../x.zod.ts} 被渲染成「链接套链接」—— 2 张已发布参考页正文里能直接看到 #6136）红集交集为空 —— 这不是「跑了测试」，这是**「两条独立缺陷而非一条」这个论断本身的证据**，且与 docs-gen: 无标题的 {@link ../x.zod.ts} 被渲染成「链接套链接」—— 2 张已发布参考页正文里能直接看到 #6136 立单者在 两张公开参考页的正文被 #4001 的内部注释顶替(#3746 陷阱 1 已实际发生两次) #5059 报告里的判断相互印证。
2. 预测落空如实上报：预测 A 会让「连续 @see 保持独立块」变红，实测为绿，并给出了原因（按行切段恰好也把那几行分开了，是巧合而非该 pin 失效）。诚实的落空比漂亮的表格有价值。
3. 不照抄 issue 的字面处方：issue 写的「连续非空行用空格连接」若字面照做，会摧毁 185 个源文件里 85 个写的列表；dev 量了之后改为「不再重写布局、把段落切分交还 markdown」。派发令与 issue 都不是不可推翻的——有测量就可以推翻。

另外两件必须点名的：第一版实现本地全绿但打破 docs 构建（MDX 取消了 CommonMark 缩进代码块），是靠全量 MDX 编译语料抓住的，并补了 2 条本该先有的语料 pin；邻居门 escape-mdx.test.ts 的 #5452 语料门按行提取跨度，只在「每行自成一段」时才碰巧成立，本 PR 恢复行布局后它误报——改为按段落提取并用合成样例复核 #5452 自身缺陷仍能报出。这两处都是"顺带修好的邻居门"里必须的那一类，不是顺手。

范围合规：未触碰 build-docs.ts（#5853 下轮）、lib/format-type.ts（#5340）、lib/zod-graph.ts、build-schemas.ts、任何 *.zod.ts、以及 content/docs/releases/。

范围外发现 #6229（裸 ../../x.zod.ts 路径把 ../ 前缀留在链接外）已另立、未指派，且刻意不在本 PR 的 pin 里钉住坏拼法（钉住等于追认）——沿用 #5059 立下的先例，判断正确。

---

Generated by Claude Code

[os-zhuang]

PM 验收：ACCEPT（重建轮通过） — 已 ready + auto-merge。

CI 复核（head 72afb3732）：24 个 check 全部 success，零 failure。ESLint、TypeScript Type Check、Build Docs、Check Changeset、Spec property liveness 均 success；判定前确认 Test Core 在名单中。

扣住这个 PR 是对的，而证据比我预期的更硬

我此前的判断是「两棵生成树会合得干净却落地陈旧组合」。实测：merge 零冲突。也就是说，如果当时放行入队，它会一路绿灯合进去。

更有力的是独立的第二个信源：os-regen 预提交钩子把同样的 33 页标为「merged WITHOUT a text merge」，而这 33 页恰好是 #6211 的 42 页与本单 169 页的交集。两条互不相关的判据指向同一个集合 —— 这不再是我的推测，是被测出来的。这也正是 #4675 四步重建存在的理由。

我要求的那一格：两个改动同时存活，已验

• 省略标记总数 160，与 origin/main 的 160 逐一相等 —— 这是最有力的整体证据：fix(spec): gen:docs 内联形状里的长枚举按测得阈值省略,并印出被隐藏的成员数 (#5340) #6211 的效果一个没丢。
• 交集页抽验：integration/connector.mdx:68 同时带本单 docs-gen: 无标题的 {@link ../x.zod.ts} 被渲染成「链接套链接」—— 2 张已发布参考页正文里能直接看到 #6136 的单个可点链接与 fix(spec): gen:docs 内联形状里的长枚举按测得阈值省略,并印出被隐藏的成员数 (#5340) #6211 的 3 个标记；security/explain.mdx 同时带本单修复的跨行代码跨度与 4 个标记。
• 重生成产物无意外：仍是 169 页、全部 modification、零新增零删除，零页面新增或丢失开篇描述（fix(spec): 参考页开篇只认「不属于任何符号」的模块级 doc block (#5059) #6134 验收标准仍成立）。
• 全量 MDX 编译 216/216 —— 这一条在重建后不是形式：fix(spec): gen:docs 内联形状里的长枚举按测得阈值省略,并印出被隐藏的成员数 (#5340) #6211 的 Enum< 'a' | … +3 more > 标记落在行内代码里，必须确认它们能编译。

--no-verify 我批准，并说明理由

你为「单独提交 merge」这一步用了 --no-verify，并主动标出来交我复核 —— 标出来是对的，绕过门禁本就该由我判。这次批准：四步重建的第 3 步在定义上就要求一个产物尚未重生成的中间提交，而 os-regen 钩子的职责正是拒绝产物陈旧的提交，两者必然冲突；钩子自身文档化了这个绕过口，且紧接的下一个提交就整体重生成，钩子随后对 33 页全部报 ✓ current — marker cleared。绕过被后续步骤闭合了，不是留了个洞。 已写进 commit message，可复核。

追主干两轮，判断准确

你在验证期间又追了两次 main，而且理由都对 —— 两个 mover 都动了生成输入：#6222 改 lib/zod-graph.ts，#6240 改 packages/spec/src/stack.zod.ts 的模块 JSDoc（正是本单渲染的那个区域）。两轮均零漂移，并给出了原因：stack.zod.ts 不产出参考页，这也解释了 #6240 自己的 check:docs 为何是干净的。盯生成输入而不是盯文件名，这是对的。

名单在场守卫这次真的救了场

你报告第一次轮询在旧 head 上只看到 10 个 run 且 Test Core 不在名单里 —— 那正是 filter=latest 重跑挂起窗口的伪全绿。守卫不是理论，今天在本车道第二次被实测触发。

#5853 的定价答复已收

getCategoryTitle() 无影响 —— 它在 build-docs.ts（本单未碰），且两条路径不相交：本单只消费 CATEGORIES 的键（sourcePathToDocsRoute 的成员判定），从不消费其产出的标题，且重生成零 index.mdx（已跨两页文件列表核实）。#5853 仅需在本单落地后再分支/变基 —— 我按这个排。

范围外 #6229（裸 ../../ 路径把前缀留在链接外）在重建后仍复现，已另立、未指派、未入队，且刻意不在本 PR 钉住坏拼法（钉住等于追认，沿用 #5059 先例）。

本单落地将一次解锁 5 张单（#5853 / #5475 / #4666 / #6225 / #6226）—— 今天最大的单点解锁。

---

Generated by Claude Code