docs: 入门文档改教仓根跑法,不再推荐会假绿的 pnpm --filter PKG test

[yinlianghui]

Fixes #3442

两处面向人和 agent 的入门文档,把 #3378 那条会静默假绿的调用当推荐用法写着。本 PR 把它们换成仓根跑法。

为什么必须改

按 #3378 的机制,pnpm --filter PKG test 让 vitest 的 root 落在包目录:根级 unit/dom/dom-heavy 三个 project 的 include(packages/** 等)相对它匹配不到任何文件,只有以绝对路径引入的 apps/console project 仍解析成功。于是跑的是 console 的 22 个文件、报 Test Files 22 passed (22),注释里声称的那个包一个都没跑,而且没有任何 "0 tests matched" 信号。

PR #3437 合并后,vitest.config.mts 的 invocation guard 会让这些命令直接非零退出。所以文档教的命令现在已不只是误导,而是根本跑不通 —— 照抄的读者会撞上一个他们没被告知过的错误框。

改了什么(共 3 处,全仓 sweep 后确认无遗漏)

文件	原	现
QUICK_REFERENCE.md:26	pnpm --filter @object-ui/console test	pnpm exec vitest run apps/console/
QUICK_REFERENCE.md:27	pnpm --filter @object-ui/core test	pnpm exec vitest run packages/core/
skills/objectui/guides/project-setup.md:309	pnpm --filter @object-ui/core test	pnpm exec vitest run packages/core/

两个文件都补上了 guard 实际打印内容的摘录,便于读者在别处撞见那个错误框时认得出;并说明 turbo run test、cd packages/x && pnpm exec vitest、以及把路径挂在 -- 后面(#3288)同属被拒之列。

两处细节:

• 单文件示例写成占位符(角括号形式,见文件内)而非 x.test.ts 这种看似真实的路径 —— guard 的 missing-path-filter 分支会拒绝指向不存在文件的具体路径,写个假的具体路径反而会让照抄的人被拒。
• project-setup.md 里把 test 从 "Scoped commands" 块拆出来单列一段:同块的 --filter PKG build / --filter "apps/*" dev 仍然正确,只有 test 不能用 --filter 表达,混在一起会让读者以为是同一族写法。

验证

三条新写进文档的命令都在仓根实跑过,确认收集到的确实是目标包的文件:

pnpm exec vitest run packages/core/ --maxWorkers=2
  RUN  v4.1.10 /home/user/objectui-issue-3442
  Test Files  64 passed (64)
       Tests  1424 passed (1424)

vitest list packages/core/ --filesOnly 收集到 64 个文件,全部在 packages/core/ 下,无一例外(旧写法收集的是 console 的 22 个)。vitest list apps/console/ --filesOnly 收集 22 个,全部在 apps/console/ 下。单文件形式 pnpm exec vitest run packages/core/src/utils/managedBy.test.ts 收集 1 个文件、26 个用例通过。

反向确认 —— 旧文档教的那条命令现在确实被拒(退出码 1,非 0):

$ pnpm --filter @object-ui/core test ; echo $?
  vitest 调用被拒绝:从包目录跑 vitest 会静默跑错测试集 (objectui#3378)
  vitest root: .../packages/core
  仓库根:      ...
  正确跑法 —— 一律在【仓库根目录】执行,路径前【不要】加 `--`
1

其他:pnpm check:control-bytes 通过(扫描 3640 个文本文件);两个文件 grep -naP 自查无控制字节;markdown fence 配平已核。

content/docs/guide/plugin-development.md:422 本就是正确形状,按 issue 要求未改动。

范围说明

• 仅改这两个文档文件,无代码改动。
• 无 changeset —— 纯文档、不涉及已发布包,与 fix(test): 拒绝两种静默假绿的 vitest 调用,并把正确跑法写进 AGENTS.md #3437 的先例一致。
• AGENTS.md 已由 fix(test): 拒绝两种静默假绿的 vitest 调用,并把正确跑法写进 AGENTS.md #3437 更新,本 PR 未碰。
• 与 17 个包各自带 vitest.config.ts 与根 vitest.config.mts 行为分叉:先回答「哪些包真的需要本地配置」 #3240(包级 test 脚本存废,维护者待定)无关:无论存废,文档都该教仓根跑法。

顺带发现(均已有 issue,未新开重复单):pnpm docs:check-links 在本分支报一个断链 content/docs/core/enhanced-actions.mdx -> /docs/components/form,经核对在 origin/main 上即已存在(该文件本 PR 未触碰),已分别记录在 #3292(断链本身)和 #3213(没有工作流跑这个检查器)。

---

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 6, 2026 4:52am