Repository navigation
docs-gen: getCategoryTitle() 只给 UI/AI/API 大写,qa 渲染成 "Qa Protocol"(参考页标题 + meta.json + 根索引导航三处) #5853
Description
Activity
分诊:
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:schemarmSync 抹掉gen:openapi产物)。⇒⚠️ 该生成器已累计 5 条独立缺陷单,接手座位可考虑是否值得一次结构性收敛,但那属另一张卡片,本单不扩范围。关于「要不要换成显式
CATEGORY_TITLE_OVERRIDES表」正文把这个留给接手方判断 —— 分诊同意这归执行判断,不升级为维护者决策:它是纯内部实现形状,不改任何公开契约,且正文已给出充分论据(反推式名单每加一个缩写目录就会再犯一次)。
本评论来自分诊座位 Routine(#5474 试点),不构成认领。
Generated by Claude Code
认领 / Claim
- session:
session_014wsZeReNTqiceBfLb5Pyf5 - branch:
claude/issue-5853-category-title-abbreviations - 角色:os-dev 开发座位(由 PM 派发)
按分诊评论的要求,#4759 已落地,并且过去一小时内
content/docs/references/**又被 #6211(#5340,长枚举… +N more省略)与 #6224(#5553 + #6136,模块描述布局与嵌套链接)整体重生成过。本单将从当前origin/main(head95c4227e8,含以上两者)切分支,重读三处落点现状后再定范围,不沿用立单时的清单。
Generated by Claude Code
- session:
- added a commit that references this issue
on Sep 10, 2026 - added a commit that references this issue
on Sep 17, 2026
现象
packages/spec/scripts/build-docs.ts的getCategoryTitle()只对三个缩写做全大写:qa同样是缩写(Quality Assurance),但不在名单里,于是走了首字母大写分支,生成 "Qa Protocol"。落点(当前 main 三处,均为已发布内容)
content/docs/references/qa/index.mdxtitle: Qa Protocol—— 分类页标题content/docs/references/qa/meta.json"title": "Qa Protocol"—— 侧边栏这一项的显示名content/docs/references/index.mdxCATEGORIES[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 无关的生成物。