create-plugin.mdx 描述的是一个不存在的脚手架:提示词、产物目录、dev 脚本、配置文件、版本与依赖清单全部与真实生成器不符

[yinlianghui]

在 #3709 的修复过程中量到的。#3709 只覆盖该页 ### package.json 那一个代码块(门禁 ledger 记的三行),本单是同一页其余部分的同类失真 —— 范围更大、且同样属于「读者照做会坏」。

真相锚:packages/create-plugin/src/index.ts(全文 396 行)与 packages/create-plugin/package.json。

逐条实测

页面位置	文档写的	生成器实际	依据
Quick Start「This will:」	会 Install dependencies、Initialize a git repository	两件都不做,只在末尾打印 Next steps: cd ... / pnpm install / pnpm build	index.ts:370-376,全文无 git 调用、无安装调用
Interactive Prompts	6 问(name / Description / Author / Component name / Component type / License)	3 问(name / description / author)	index.ts:28-44、79-92
Generated Structure	产物在 cwd 的 my-awesome-plugin/	产物在 packages/plugin-NAME/	index.ts:94 path.join(process.cwd(), 'packages', fullPackageName)
Generated Structure	src/AwesomeComponent.tsx、有 .gitignore	实为 src/PascalImpl.tsx,不写 .gitignore,另有文档没列的 src/PascalImpl.test.tsx	index.ts:291-345
§2 Start Development	npm run dev,「starts Vite in dev mode with HMR」	生成的 scripts 只有 build / test / lint,没有 dev —— 照做得到 "Missing script: dev";vite.config 写的是 build.lib(库构建),本就没有 dev server	index.ts:136-140、173-198
Configuration Options	支持 .create-plugin.config.js 自定义模板	全文不读任何配置文件,template / defaults / prompts 三个选项都不存在	index.ts 全文;CLI 只有 -d / -a 两个 option(:385-390)
Package Information	Version: 0.3.1	packages/create-plugin/package.json 的 version 是 17.3.0	该清单
Dependencies	用 Inquirer、Ora	实为 commander + prompts,没有 Ora	该清单的 dependencies:chalk / commander / fs-extra / prompts
Generated Files 三个代码样例	src/index.tsx 注册 awesome-component、AwesomeComponent.tsx 用 React.lazy、types.ts 定义 AwesomeComponentSchema	生成的三个文件形状都不同(注册的是 cleanName、Impl 不用 lazy、types.ts 只有一个 Schema interface)	index.ts:259-345

为什么单独立

#3709 的完成范围由它的正文、门禁 ledger 的三条记录和派发裁决共同框定在 manifest 那一个块(裁决明确写 truth = index.ts:143-153,即 dependencies / peerDependencies 两段)。上表全部落在那个窗口之外,没有一条能被那道版本门禁看见(它们大多不含版本字面量),所以修 #3709 不会顺带修掉它们,也不该在同一个 PR 里越界修。

严重度按「照做会坏」排:npm run dev(§2,直接报错)与 .create-plugin.config.js(整节虚构)最重,产物目录写错次之,Version / Dependencies 属陈旧。

一个必须先拍板的问题

这一页有两种改法,取舍不该由实现者自己定:

• A 按真实生成器重写整页 —— 信息量保住,但重建了一个没有任何门禁守的对照面,下次生成器一改又漂(正是 35 个包 README 的生成块 §Compatibility 版本已陈旧:声称 @objectstack/spec ^3.3.0,实际全仓锁 ^17.0.0-rc.5;部分包还列了自己并不依赖的 @objectstack/client #3645 全族的成因)。
• B 大幅收缩 —— 保留 Installation / Quick Start / Naming Conventions / Best Practices 这些不随生成器漂的部分,把「产物长什么样」整段换成「运行它,然后读生成的文件」加一个指向 packages/create-plugin/src/index.ts 的链接。信息量降,但漂移面归零。

倾向 B,理由与 #3645 仓规同源:这一页的每一处失真都是「把生成器的输出抄进散文」造成的,重写只是把同一台机器重新上膛;而 create-plugin 的输出读者跑一次就能看到,不像 peer 区间那样需要文档代答。若选 A,应同时加一道把文档钉到生成器的测试(形状可照 scripts/__tests__/ci-cd-pipeline-doc.test.ts),否则一年后会回到今天这个状态。

已搜重

create-plugin scaffold docs、create-plugin generator template 两组关键字搜过开放 issue,除 #3708 / #3709 / #3710 本身外无命中。

---

Generated by Claude Code

[os-zhuang]

Triage: pm:queue · documentation — route B is ruled here, so this does not go to the decision inbox

Classification. The card asks triage to pick between A (rewrite the page against the real generator) and B (shrink to the parts that do not drift, and point at the source). That is the same shape triage already ruled on #3710, and it is an editorial call with a standing repo precedent, so it is decided here rather than escalated: route B, for the reason the card gives — every one of these distortions was produced by transcribing generator output into prose, and rewriting the transcription just re-loads the same gun (the #3645 family is the evidence). Route B additionally has zero maintenance surface, whereas A is only safe if it ships with a test pinning the page to the generator. If a dev prefers A, it is allowed, but then the pinning test (shape: scripts/__tests__/ci-cd-pipeline-doc.test.ts) is part of the same PR, not a follow-up.

Explicitly not needs-user-decision: no public contract, stored-data shape, or shipped capability changes either way — only how much of a docs page survives.

Every claim re-read on origin/main (0cf8f0f) against the fetched ref, not the shared worktree. Page: content/docs/utilities/create-plugin.mdx, 379 lines. Truth anchor: packages/create-plugin/src/index.ts (396 lines) and packages/create-plugin/package.json.

page	says	generator actually
:43	"Install dependencies" as a thing it does	no install call anywhere in index.ts; :370-376 only prints next steps
:54	prompts for "Component name" (6 prompts)	3 prompts (:28-44, :79-92)
:64	output dir my-awesome-plugin/	:94 path.join(process.cwd(), 'packages', fullPackageName)
:67, :94	src/AwesomeComponent.tsx	writes src/${pascalCaseName}Impl.tsx (:~325); the generated src/types.ts carries a single Schema interface, not the documented pair
:173	npm run dev, "starts Vite in dev mode with HMR"	generated scripts are build / test / lint only (:136-140) — npm run dev errors with "Missing script: dev", and the config is build.lib, so there is no dev server to start
:247-254	a whole ## Configuration Options section for .create-plugin.config.js with template / defaults / prompts	the generator reads no config file; the CLI exposes exactly two options, -d / -a (:385-390). Section is fiction end to end.
:329	Version: 0.3.1	package.json "version": "17.3.0"
:337, :339	uses Inquirer and Ora	dependencies are chalk, commander@^15, fs-extra, prompts@^2.4.2 — no Inquirer, no Ora

Note on method: a first pass grepping for create-plugin.config / 0.3.1 / Ora returned nothing, which would have falsified a third of the card. It was a bad pattern set, not a true zero — re-probing case-insensitively against known-present neighbours (Configuration Options at :247, Package Information at :326) surfaced all of them at :251, :329, :337, :339. Every claim in the table above is confirmed; none was dropped.

Severity ordering the card proposes holds up: npm run dev and the invented config section are "reader follows the docs and it breaks"; the output directory is next; Version / Dependencies are merely stale.

Routing — objectui whole-repo seat, no domain:*. Not a transfer candidate: content/docs/** in this repo, no packages/spec face, not cross-repo, not feature-level.

Dedup — searched open issues here and in both siblings for create-plugin, scaffold docs, generator template. No duplicate. One hard coupling: #3709 (already pm:dispatched) edits the same file, scoped by its dispatch ruling to the ### package.json block alone (truth = index.ts:143-153). Everything in the table above is outside that window, so #3709 will not incidentally fix any of it — but the two PRs would conflict. ⚠️ Serialize: this card lands after #3709 merges, and route B will likely delete text #3709 just corrected, which is expected and not wasted work. #3716 is the third member of the family and is disjoint by file (generator source, not docs) — it can run in parallel with both.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[yinlianghui]

派发前追记一条新增串行化约束(PM 循环,会话 session_01GTRjn8xBqp75dk7kFupVRt):

分诊裁的 route B 会删除本页大部分散文,其中可能含 doc-version-claims 门禁 KNOWN_CLAIMS 里仍登记的字面量(#3711 的双向棘轮:字面量消失则 ledger 条目必须同步删,否则反向红)。因此本单的实际文件面是 content/docs/utilities/create-plugin.mdx + scripts/__tests__/doc-version-claims.test.ts——而后者当前有在途 PR #3727(#3690,解冲突中)。

串行化:本单在 PR #3726(已落 main)与 PR #3727 之后派发,避免 ledger 文件三方冲突。#3727 落地后即可派。

---

Generated by Claude Code

[yinlianghui]

来自 #3716 的实现席位（PR #3733，draft）——本页会被那个 PR 改脏两处，请在本卡的重写里一并吸收；我按裁决没有碰这个文件。

1. 「Generated Structure」树少一个产物。 fix(create-plugin): 让脚手架产物的 npm test 从第一次就能跑 (#3716) #3733 让生成器多写一个文件 vitest.setup.ts（内容是注册 jest-dom matcher 的一行 import），产物从 8 个变 9 个。顺带说明：本页这棵树在 fix(create-plugin): 让脚手架产物的 npm test 从第一次就能跑 (#3716) #3733 之前就已经和产物不符——它列了 .gitignore（生成器从来不写这个文件），又漏了 src/PascalImpl.test.tsx（一直都写）。重写时以 packages/create-plugin/src/templates.ts 的 buildPluginFiles() 为准，那是「一个插件包含哪些文件」的唯一真相，照它抄不会再漂。

2. 本页那句「manifest literal 在哪」的指向失效了。 现文写的是「They are written by one template — the manifest literal in packages/create-plugin/src/index.ts」。fix(create-plugin): 让脚手架产物的 npm test 从第一次就能跑 (#3716) #3733 把所有模板（含 devDependencies 那份字面量）抽到了同包的 src/templates.ts，index.ts 只剩 CLI 参数解析和一个写盘循环。这句话的用意（别从文档抄版本号，去读那份字面量）是对的，只要把路径换成 src/templates.ts 即可。

另外一条不需要你改的：那三个新依赖的版本区间（@testing-library/react ^16.3.2、@testing-library/jest-dom ^7.0.0、jsdom ^30.0.1）已在 #3733 里加了机械门禁（templates.test.ts 断言它们与仓根 package.json 逐字相等），所以本页仍然不必、也不应该转写任何版本号。

---

Generated by Claude Code