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

[yinlianghui]

Fixes #3715

按分诊裁决走 route B(收缩),不做 route A 全量重写:本页每一处失真都是「把生成器产物转写成散文」造成的,重写转写等于把同一把枪重新上膛(#3645 家族)。所以「产物长什么样」的整段一律删除并指路,只留下不会自己变旧的那部分。

真相锚:packages/create-plugin/src/templates.ts 与 src/index.ts,对 origin/main @ 0c28a0720 逐条实测(#3733 已落 main,模板已在 templates.ts)。全页 374 行 → 181 行(+123 / -315)。

删除(照做即坏 / 纯虚构)

删掉的内容	实测真相
Quick Start「This will: Install dependencies / Initialize a git repository」	两件都不做。index.ts 全文只有一处 pnpm install 字样,是打印给用户的 next step(:132),没有任何 exec / spawn / git 调用
Interactive Prompts 的 6 问假脚本(含 Component name / Component type / License)	传了名字时只问 2 个(description / author,:82-95);不传名字才多问一个名字
Generated Structure 树(产物在 cwd 的 my-awesome-plugin/,列 .gitignore,缺示例测试)	实际写到 path.join(process.cwd(), 'packages', fullPackageName)(:97);产物 9 个,不含 .gitignore,含示例测试与 vitest.setup.ts
Generated Files 四段代码样例(src/AwesomeComponent.tsx、export * from './types'、Props/Schema 成对的 types.ts)	形状全不符:入口从 PascalImpl 导入并在模块顶层注册,types.ts 只有一个 Schema 接口
§2 Start Development 的 npm run dev + "starts Vite in dev mode with HMR"	生成 scripts 只有 build / test / lint;配置是 build.lib,没有 dev server 可启。照做得到 "Missing script: dev" —— 本单最重的一条
§Configuration Options 整节(.create-plugin.config.js 的 template / defaults / prompts)	生成器不读任何配置文件,整节虚构
Version: 0.3.1	实际 17.3.0;按 #3711 的取向直接删字面量、改指 npm 页
§Dependencies(Inquirer / Ora)	实为 chalk / commander / fs-extra / prompts;而且 CLI 自身依赖对读者无用,整节删除
Troubleshooting 的 "Template Not Found" / "Dependencies Not Installing"	生成器没有模板目录概念、也不装依赖,两条都是虚构故障
§Features 的营销条目	其中 "Documentation Template - Includes README and docs" 只写 README;整体信息量为零,一并删
### package.json 一节(#3726 刚订正过)	分诊已预告「route B 很可能删掉 #3709/#3726 刚订正的文字,这是预期、不是白干」。其中「不要从文档抄版本号,去读那份字面量」的用意保留,路径按 #3716 席位的追评从 src/index.ts 改成 src/templates.ts

指路(取代转写)

• §What It Generates 明说本页不复制产物树与产物文件,指向 buildPluginFiles() in src/templates.ts —— 「一个插件包含哪些文件」的唯一真相,index.ts 只是写盘循环。没有任何文件清单被手工维护(create-plugin 生成的插件跑不了自己的测试:模板写入 test 文件与 test 脚本,却没在 devDependencies 里声明 @testing-library/react 与 jest-dom #3716 席位的交接项 1)。
• 依赖区间一个不写,改为说明它们在那份模板字面量里、并由 src/__tests__/templates.test.ts 机械锚定到仓内声明(交接项 3)。
• CLI 选项不逐条转写,改为指 --help;脚本清单不转写,改为「新包里跑 pnpm run 看它到底有哪些」—— 两句都是自更新的真相。
• next steps 不转写,改为「生成器跑完会自己打印,照它做」。

保留 / 新增(都是不会自己变旧的事实)

• Installation、Naming Conventions、Best Practices、Example Plugins、Package Information、Next Steps、Need Help? 的骨架保留。Package Information 仿 runner.mdx 的写法(docs(runner): 删掉 runner.mdx 的幽灵目录与「内置示例 schema」断言,重写 Package Information #3616):只留名字 / binary / license,版本改指 npm 页。
• Best Practices 收成 4 条建议(lazy 边界、真实 fallback、导出 schema 类型、注册键即公开契约),并明说这是给作者的建议而非脚手架已做之事 —— 旧页把它读成了「产物长这样」。
• 新增三条读者真正会踩、且由结构决定的事实:必须在 pnpm workspace 根目录运行(产物写到 cwd 的 packages/ 下,依赖是 workspace:*,tsconfig 往上两级 extends);一个名字同时决定四样东西(目录 / 包名 / 注册 type 键 / PascalCase 组件名),plugin- 前缀会被剥掉;发布用 pnpm publish(pnpm 打包时会把 workspace:* 改写成真实区间,npm publish 会把字面量原样发出去)。
• Troubleshooting 换成三条真实故障:目录已存在即中止、名字校验(小写字母 / 数字 / 连字符)、在 workspace 外面跑导致依赖与 tsconfig 解析不到。

第二个 commit:被 #3742 追上的那一句

b8b219bac 是分支开着的时候 PR #3754(#3742)落 main 触发的:那个 PR 把 templates.test.ts 从「三条测试区间取自仓内」升级成「每一条 devDependency 区间都被锚定,没有未钉的」。本页原写「the testing ones are asserted…」在我的 fetch 点是准确的,合并后就变成了低估 —— 正是本次收缩要消灭的那种漂移,所以改成只说锚定这件事本身,不说子集、不说条数。因为禁止 force-push,这一句以追加 commit 落下而非 rebase 重写。

Ledger(#3711 双向棘轮)

无需删任何 KNOWN_CLAIMS 行:该 ledger 里本就没有 create-plugin.mdx 的登记行(仅在文件头注释中作为 #3709 的案例被提及,不是条目)。原因是它的匹配需要「包名与版本同行相邻」,而旧页的 0.3.1 单独一行,从未被扫成 claim。改动前后各跑一次确认:

# 改动前(把页面 checkout 回 main 的版本)
Test Files  1 passed (1)
     Tests  10 passed (10)

新写的散文也不含任何版本字面量,所以棘轮上行方向同样不会红。

验证

$ node scripts/check-control-bytes.mjs
✅  check-control-bytes: OK (scanned 3692 tracked text file(s); skipped 85 binary).
$ grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' content/docs/utilities/create-plugin.mdx
(clean)
$ node scripts/check-doc-links.mjs
Links are valid across 7 scan roots.
$ flock /tmp/os-heavy-verify.lock -c 'NODE_OPTIONS=--max-old-space-size=4096 pnpm exec vitest run scripts/__tests__ --maxWorkers=2'
Test Files  20 passed (20)
     Tests  369 passed (369)

本地另外单独编译过 MDX(用仓内 @mdx-js/mdx@3.1.1 直接 compile() 本页 → OK,16611 bytes JSX;对照编译未改动的 runner.mdx 同样 OK,证明这个检查不是空转)。

订正一处我先前写错的话:这段最初写的是「ci.yml 的 paths-ignore 含 content/**,纯 docs PR 不会启动 Build Docs」。错的,而且错得正是本单批评的那个模式 —— 我把 Build Docs job 里一段讲历史的注释读成了当前事实。实际上 ci.yml 的 pull_request 触发器自 #3523 起已经没有 paths-ignore(只有 push: 还保留一份),路径判断移进了 job 内部;所以本 PR 确实拉起了 Build Docs,而它的 "Check for docs changes" 步看到 content/ 有改动 → should_run=true → 真的构建站点。本地那次 MDX 编译因此只是提前一步的自检,不是 CI 缺口的补丁。

Changeset:无。 纯文档订正,依 AGENTS.md 与同族先例(PR #3698 / #3726 / #3616 都是 docs-only 且无 changeset)。

未触碰 packages/create-plugin/**(#3742 在途,现已落 main)、scripts/__tests__/doc-version-claims.test.ts(无行可删)、content/docs/releases/。与 origin/main @ e473b6c29 实测无冲突(git merge-tree:0 处冲突标记)。

越界发现

已另开 #3759(finding,未排队、未指派):生成的 src/types.ts 是死产物 —— 没有任何生成源文件 import 它,生成的 exports map 又只暴露 .,那个 Schema 接口在包内无人用、包外不可达。与 #3742 / #3755 同族同文件但范围互不覆盖。有意思的是,本 PR 删掉的那段虚构文档写的 export * from './types' 恰好比真实模板更合理。本 PR 未改一行生成器代码。

---

Generated by Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 8, 2026 12:12pm