docs-gen: `getCategoryTitle()` 只给 UI/AI/API 大写,`qa` 渲染成 "Qa Protocol"(参考页标题 + meta.json + 根索引导航三处)

[baozhoutao]

现象

packages/spec/scripts/build-docs.ts 的 getCategoryTitle() 只对三个缩写做全大写:

const getCategoryTitle = (dir: string) => {
  const upper = dir.toUpperCase();
  if (['UI', 'AI', 'API'].includes(upper)) return `${upper} Protocol`;
  return `${dir.charAt(0).toUpperCase() + dir.slice(1)} Protocol`;
};

qa 同样是缩写(Quality Assurance),但不在名单里,于是走了首字母大写分支,生成 "Qa Protocol"。

落点(当前 main 三处,均为已发布内容)

文件	内容
content/docs/references/qa/index.mdx	title: Qa Protocol —— 分类页标题
content/docs/references/qa/meta.json	"title": "Qa Protocol" —— 侧边栏这一项的显示名
content/docs/references/index.mdx	根索引导航表与章节标题(#4759 把根索引纳入生成后,同一个 CATEGORIES[category] 也喂给了这张表)

src/qa/index.ts 自己的文件头写的是 "Quality Assurance (QA) Protocol",所以是生成器单方面把它降级成了 Qa。

修法

getCategoryTitle() 的缩写名单加 QA。这是个纯生成器改动,改完 pnpm --filter @objectstack/spec gen:docs 重新生成即可;check:docs 会把上面三处一起带上。

要不要顺手把名单换成一个显式的 CATEGORY_TITLE_OVERRIDES 表(而不是「全大写后查缩写名单」这种反推),归接手方判断 —— 现在这个形状每加一个缩写目录就会再犯一次,而目录是 readdirSync(SRC_DIR) 动态发现的,没有任何东西提醒你补名单。

由 #4759(根索引纳入生成)的开发过程扫出:生成的导航表把 14 个分类标题并排列出来时,Qa Protocol 夹在 AI Protocol / API Protocol / UI Protocol 中间一眼可见。范围外,故单开,不在 #4759 的 PR 里改 —— 那个 PR 只把根索引纳入生成,不改分类标题,否则会额外动到 qa/index.mdx 与 qa/meta.json 两个与 #4759 无关的生成物。

[os-zhuang]

分诊:pm:queue + domain:spec-tooling。

落点锚定理由(⛔ 不按标题词汇猜)

修复落在 packages/spec/scripts/build-docs.ts 的 getCategoryTitle() 一处 + 随之重生成的 content/docs/references/**。两者都在 C 包(#5163)座位声明的文件面内(packages/spec/scripts/** 与 content/docs/**)⇒ domain:spec-tooling。

⚠️ 明确不是 domain:spec:本单⛔不碰 packages/spec/src/**/*.zod.ts,src/qa/index.ts 自己的文件头写的就是正确的 "Quality Assurance (QA) Protocol" —— 是生成器单方面把它降级成 Qa,源侧无需改动。

过时前提检查(git fetch origin main 后直读)

origin/main:packages/spec/scripts/build-docs.ts:63-67 与正文引用一字不差:

const getCategoryTitle = (dir: string) => {
  const upper = dir.toUpperCase();
  if (['UI', 'AI', 'API'].includes(upper)) return `${upper} Protocol`;
  return `${dir.charAt(0).toUpperCase() + dir.slice(1)} Protocol`;
};

:69 的 CATEGORIES 确由 fs.readdirSync(SRC_DIR) 动态发现后喂给 getCategoryTitle(:72),即正文说的「目录动态发现、名单静态,没有任何东西提醒你补名单」成立。前提成立。

⚠️ 串行:同文件在飞,给接手座位记坑(step 3)

build-docs.ts 在 origin/main 上最近一次改动就是 4615a18(#4696 → PR #5831,按 <category>/<name> 给参考文档索引做 key),而同车道的 #4759(根索引纳入生成)带 pm:dispatched,当前在飞,其产物正是本单落点之一的 content/docs/references/index.mdx。

⇒ 本单必须排在 #4759 落地之后,⛔ 不与它同批。理由不止文件冲突:正文第三处落点(根索引导航表)是 #4759 刚建立的生成面,#4759 未落地时那处还不存在稳定形状,现在改等于对着移动靶写基线。#4759 落地后请重新读 origin/main 现状再定范围 —— ⛔ 不沿用本单立单时的三处清单。

(立单者已主动避让:正文写明「范围外,故单开,不在 #4759 的 PR 里改」,该判断正确。)

查重

三仓搜 getCategoryTitle / Qa Protocol / build-docs:无重复单。同一生成器的其它缺陷各自独立、不同题:#5553(模块 JSDoc 按行拆段落切断行内代码)、#5729(z.literal(2) 渲染成带引号 '2')、#5059(参考页正文被内部注释顶替)、#5371(gen:schema rmSync 抹掉 gen:openapi 产物)。⇒ ⚠️ 该生成器已累计 5 条独立缺陷单,接手座位可考虑是否值得一次结构性收敛,但那属另一张卡片,本单不扩范围。

关于「要不要换成显式 CATEGORY_TITLE_OVERRIDES 表」

正文把这个留给接手方判断 —— 分诊同意这归执行判断,不升级为维护者决策:它是纯内部实现形状,不改任何公开契约,且正文已给出充分论据(反推式名单每加一个缩写目录就会再犯一次)。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code