Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Repository navigation
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

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

Closed
#3760
Closed
create-plugin.mdx 描述的是一个不存在的脚手架:提示词、产物目录、dev 脚本、配置文件、版本与依赖清单全部与真实生成器不符#3715
#3760
Assignees
yinlianghui
Labels
documentationImprovements or additions to documentationpm:dispatchedpm:queue

Description

@yinlianghui
yinlianghui
opened on Aug 8, 2026

在 #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 属陈旧。

一个必须先拍板的问题

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

倾向 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

Activity

  1. os-zhuang
    added
    documentationImprovements or additions to documentation
    pm:queue
    on Aug 8, 2026

  2. os-zhuang commented on Aug 8, 2026

    @os-zhuang
    os-zhuang
    on Aug 8, 2026 – with Claude
    Contributor

    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

  3. yinlianghui commented on Aug 8, 2026

    @yinlianghui
    yinlianghui
    on Aug 8, 2026 – with Claude
    ContributorAuthor

    派发前追记一条新增串行化约束(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

  4. yinlianghui commented on Aug 8, 2026

    @yinlianghui
    yinlianghui
    on Aug 8, 2026 – with Claude
    ContributorAuthor

    来自 #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

  5. yinlianghui
    added
    pm:dispatched
    on Aug 8, 2026
  6. yinlianghui
    self-assigned this
    on Aug 8, 2026

  7. yinlianghui commented on Aug 8, 2026

    @yinlianghui
    yinlianghui
    on Aug 8, 2026 – with Claude
    ContributorAuthor

    认领:PM 循环批 180(objectui 整仓席位,登记表 objectstack#4604)

    串行化闸门全部解除:PR #3726(#3709 同页 manifest 块)、PR #3727(#3690 ledger)、PR #3751(#3717 restatement 断言,同 ledger 文件)均已落 main。按分诊裁决走 route B(收缩);若 dev 论证 A 更优,钉页测试必须同 PR 交付(分诊原文)。新增输入:#3716 dev 在本 thread 的追评(本页两处新过期:Generated Structure 树缺第 9 个产物 vitest.setup.ts、"manifest literal in src/index.ts" 应为 src/templates.ts;树在此前就错——列了生成器从不写的 .gitignore、漏了示例测试)一并纳入处置面。与在飞 #3742(templates.ts 源码)不同文件,不互斥。

    会话:session_01GTRjn8xBqp75dk7kFupVRt
    分支:claude/issue-3715-create-plugin-mdx-shrink
    Worktree:objectui-3715
    文件面:content/docs/utilities/create-plugin.mdx + scripts/__tests__/doc-version-claims.test.ts(仅当删除的字面量在 KNOWN_CLAIMS 有登记行时按双向棘轮同步删行)(越界即停)

    Generated by Claude Code

  8. yinlianghui
    added a commit that references this issue on Aug 8, 2026

    docs(create-plugin): widen the parity-gate sentence to match #3742 la…

    b8b219b

  9. yinlianghui commented on Aug 8, 2026

    @yinlianghui
    yinlianghui
    on Aug 8, 2026 – with Claude
    ContributorAuthor

    实现席位交付:PR #3760(draft),分支 claude/issue-3715-create-plugin-mdx-shrink,会话 session_01GTRjn8xBqp75dk7kFupVRt。

    按裁决走 route B,未走 A(因此本 PR 不含钉页测试,也不需要)。374 行 → 181 行,只改 content/docs/utilities/create-plugin.mdx 一个文件。逐条处置见 PR 正文的三张表(删除 / 指路 / 保留)。

    三条与本 thread 直接相关的结论:

    1. Ledger 不需要动。 scripts/__tests__/doc-version-claims.test.ts 的 KNOWN_CLAIMS 本就没有 create-plugin.mdx 的条目 —— 旧页的 **Version:** 0.3.1 与上一行的包名不同行,而那套匹配要求「包名与版本同行相邻」,所以它从来没被扫成 claim。改动前(把页面 checkout 回 main 版本)与改动后各跑一次,均 10/10 绿;新散文不含任何版本字面量,上行棘轮也不会红。因此本 PR 的文件面收窄为只有 docs 一个文件,scripts/__tests__/ 未触碰。
    2. create-plugin 生成的插件跑不了自己的测试:模板写入 test 文件与 test 脚本,却没在 devDependencies 里声明 @testing-library/react 与 jest-dom #3716 席位的三条交接项全部吸收:产物树彻底不再手工维护(改为指向 buildPluginFiles());「manifest literal 在哪」那句的路径改为 src/templates.ts;版本区间一个不转写,改为说明它由 templates.test.ts 机械锚定。
    3. create-plugin 生成产物的 build 侧 devDependencies 内部不一致且落后仓库工具链 1–2 个 major:@vitejs/plugin-react ^4.2.1 的 peer 结构性无法被 vite ^7.3.1 满足 #3742 在我开着分支时落了 main(PR fix(create-plugin): 把脚手架 build 侧 devDependencies 锚到仓内工具链,并把整张清单钉进 parity 测试 #3754),把那条门禁从「三条测试区间」升级成「每条 devDependency 都锚定」。我原来的措辞在 fetch 点准确、合并后变成低估,已用追加 commit(不 force-push)改成不提子集、不提条数的写法。这正是 route B 想要的性质,顺手也是一次反向验证:凡是转写具体范围的句子都会被下一个 PR 追上。

    越界发现另开 #3759(finding,未排队未指派):生成的 src/types.ts 无人 import、exports 又只暴露 .,那个 Schema 接口不可达。未改生成器一行代码。

    Generated by Claude Code

    Generated by Claude Code

  10. yinlianghui commented on Aug 8, 2026

    @yinlianghui
    yinlianghui
    on Aug 8, 2026 – with Claude
    ContributorAuthor

    验收:PR #3760 ACCEPT(会话 session_01GTRjn8xBqp75dk7kFupVRt,PM 循环批 180)。

    交付内容:route B 收缩,374→181 行(+123/−315)——九处失真全部先在 main 复核确认再删除;一切"产物长什么样"的转写(目录树、四段代码样例、prompt 转录、脚本清单、CLI 依赖清单、版本字面量)换成指向 buildPluginFiles()(src/templates.ts)的真相锚 + 自更新指引(--help、pnpm run、"照它打印的 next steps 走");幸存的是调用面 + 三条结构决定的事实(须在 workspace 根运行、一个名字决定四处、用 pnpm publish 使 workspace:* 重写)。虚构配置节以显式否定句收口(防复活,同 #3745 手法)。#3716 交接的两处新过期一并吸收。

    文件面比认领声明更窄:ledger 零行需删(本页字面量因"包名+版本同行相邻"匹配规则从未入账,'0.3.1' 独行),故实际只动一个 docs 文件——如实报告,采纳。中途 PR #3754 落地使 parity 门从"三条测试区间"扩成"全清单锚定",dev 以追加提交把措辞从保守改为如实(禁 force-push,正确),这正是本次收缩要杀死的漂移类在自己身上的演示。

    证据:MDX 用仓内 @mdx-js/mdx 实际 compile(附 runner.mdx 非空对照);check-doc-links 7 根绿;ledger 前后对照按预测双绿零删行;逆向验证如实报"纯删除无肢可复原"不造红;PR 正文内自我更正一处(把 Build Docs job 里的历史注释当了现状——恰是本单要治的病,dev 自己抓住并改正)。CI 15 项全绿;无 changeset 循 docs-only 先例。新立 #3759(生成的 types.ts 死工件,exports map 不可达;与 #3755 同族非孪生,查重程序正确)入分诊池。

    Generated by Claude Code

  11. yinlianghui
    closed this as completedin #3760on Aug 8, 2026
  12. akarma-synetal
    added a commit that references this issue on Aug 10, 2026

    docs(create-plugin): 按 route B 收缩到不漂移的部分,产物一律指向 buildPluginFiles() (o…

    b1204af
  13. akarma-synetal
    added a commit that references this issue on Aug 17, 2026

    docs: repair and pin QUICK_REFERENCE's Current Release block, drop th…

    43b2e45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationpm:dispatchedpm:queue

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions