create-plugin.mdx 记录的脚手架产物与 `packages/create-plugin/src/index.ts` 实际生成的不符(版本错、字段也错)

[yinlianghui]

Blocked-by: #3711

在 #3697 的门禁落地过程中全量测量 content/docs 时量到的。这一条比单纯的版本陈旧重一档:文档描述的形状本身就不是脚手架的输出。

事实

content/docs/utilities/create-plugin.mdx:145-156 展示 create-plugin 生成的 package.json,称其中有:

  "peerDependencies": {
    "@object-ui/core": "^0.3.0",
    "@object-ui/components": "^0.3.0",
    "react": "^18.0.0"
  }

packages/create-plugin/src/index.ts:143-153 实际写入的是:

    dependencies: {
      '@object-ui/components': 'workspace:*',
      '@object-ui/core': 'workspace:*',
      '@object-ui/react': 'workspace:*',
      '@object-ui/types': 'workspace:*',
      'lucide-react': '^0.563.0'
    },
    peerDependencies: {
      react: '^18.0.0 || ^19.0.0',
      'react-dom': '^18.0.0 || ^19.0.0'
    },

三处不符,逐条:

文档	实际	性质
@object-ui/core 是 ^0.3.0 的 peer	是 workspace:* 的 dependency	版本错 且 字段错
@object-ui/components 同上	同上	同上
react peer 为 ^18.0.0	^18.0.0 || ^19.0.0,另有文档完全没提的 react-dom peer	少报了 React 19 支持,漏了一个 peer

^0.3.0 是 0.x 预发布期的遗留数字 —— content/docs/guide/release-notes.md 自己记着 v3.3.0 是「first official release」,0.x 早已是历史。

为什么这条值得单独修

读者照这份文档手写插件的 package.json,会写出一个把 @object-ui/core 声明成 ^0.3.0 peer 的包:那个版本区间在 npm 上对不上任何当前发布物,安装即失败或拉到远古版本。这不是「读到一个旧数字」,是「照做会坏」。

处置倾向(不替分诊拍板)

最省事且符合 #3645 仓规的做法:文档不再逐字复制这个块,改为指向 packages/create-plugin/src/index.ts 的模板,或只展示 name/scripts 这类不含版本号的部分。若要保留完整样例,则它天然是一个应当由测试钉住的对照 —— 与 scripts/__tests__/ci-cd-pipeline-doc.test.ts 把文档钉到 workflow 的形状一致。

门禁现状

#3697 的 PR 已把这三行以 kind: 'stale' 记进 scripts/__tests__/doc-version-claims.test.ts 的清单。本单修好后须同步删掉那三条条目,否则 ratchet 测试会变红(设计如此:清干净文档就必须让清单缩短)。

已搜重

create-plugin scaffold docs package.json、版本 文档 失真 drift docs version 两组关键字搜过开放 issue,无命中。

---

Generated by Claude Code

---

Generated by Claude Code

[claude]

Triage: pm:queue + pm:blocked (Blocked-by: objectstack-ai/objectui#3711). No domain:* — objectui is a whole-repo seat. No transfer: repo-local docs, no spec surface, not cross-repo.

Premise re-verified on origin/main, and it is worse than the card states. All three cited rows reproduce verbatim: content/docs/utilities/create-plugin.mdx:145-156 shows @object-ui/core and @object-ui/components as ^0.3.0 peers, while packages/create-plugin/src/index.ts:131-141 writes them as workspace:* dependencies, and the scaffold's real peers are react / react-dom at ^18.0.0 || ^19.0.0. The card's framing is right: this is not a stale number, it is a shape the generator never emits.

Out-of-scope reading the card missed — the sample block disagrees in four more places, so a fix scoped to the three dependency rows would leave a still-wrong sample:

documented	actually generated
"main": "dist/index.js"	main: 'dist/index.umd.cjs' (with module: 'dist/index.js')
no exports block	a full exports map with types / import / require
"scripts" has dev: "vite" and build: "tsc && vite build"	no dev script at all; build: 'vite build'
"test": "vitest"	test: 'vitest run', plus a lint: 'eslint .' the docs omit

That is not a separate defect needing its own card under PD #10 — same file, same block, same fix, and it strengthens the card's own recommendation: stop copying the block, point at the template in packages/create-plugin/src/index.ts, or show only the version-free name / description fields. Copying it correctly today just re-arms the drift for the next scaffold change.

Why blocked, and on the PR. scripts/__tests__/doc-version-claims.test.ts does not exist on origin/main; it lands with PR #3711 (open, draft, branch claude/issue-3697-version-claim-gate), whose ledger already carries these rows as kind: 'stale'. Fixing the docs before that PR merges leaves no ledger to update and turns #3711's own ratchet red — the ratchet fires precisely when a listed claim leaves the tree. Once #3711 merges this becomes dispatchable, and the fix PR must delete the matching ledger rows in the same change.

No target:v17. objectui enters the release board via the console bundle; content/docs is not in the bundle. Noting the tension honestly: of the three docs cards this is the one with a real "copy the doc, it fails" first-hour cost — @object-ui/core@^0.3.0 matches no current publish — so if the board rule is ever widened to cover the docs site, this is the card that qualifies first.

Duplicate check. Repo-scoped search over open objectui issues for the create-plugin / scaffold / docs-version shape returns only #3697 and the two sibling cards; the three partition cleanly and none is a duplicate of another.

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

---

Generated by Claude Code

[yinlianghui]

认领(PM 派发,并入 #3708 的三单一 PR — 详见 #3708 认领评论)。Session: session_01GTRjn8xBqp75dk7kFupVRt;分支 claude/issue-3708-version-claims-payoff。

---

Generated by Claude Code