docs(getting-started): 把 for-developers 的 src/ 目录树按实况重画，并让 docs-drift 守卫看得懂目录树 (#984)

[yinlianghui]

Fixes #984

改了什么

① 文档：getting-started/for-developers（三语同步）

点名的两处残留（#512 删掉的 agents 面）：

• 目录树里的 agents/ 分支删除 —— src/agents/ 不存在，find src -name '*.agent.ts' 零命中。
• 后缀表里 `*.agent.ts` | AI agent 一行删除。
• 附带同型第三处：「Add an AI skill」原文让读者「把 skill 名称加入 src/agents/ 中对应的 agent」，这一步已不存在（从 src/skills/index.ts 导出即是全部接线），改写为实况；树后补一句说明 HotCRM 只写 skills 不写 agent，并内链到 AI Skills 页（zh 内链不带锚）。

整棵树逐目录核对（不只改点名两处）—— 与真实 src/ 18 个目录对了一遍：

核对结果	目录
幻影（删）	agents/
缺项（补）	hooks/、mappings/、docs/、interfaces/
原样保留（存在且正确）	objects/ actions/ flows/ skills/ apps/ views/ pages/ dashboards/ reports/ datasets/ profiles/ sharing/ translations/ data/

补项的注释按实况写：hooks/ 是把 src/objects/*.hook.ts 汇总交给 stack 的 barrel；mappings/ 是导入用的列到字段映射（config 里 mappings: 注册）；docs/ 是 ADR-0046 收进 dist/objectstack.json 一起分发的应用文档；interfaces/ 目前只有版权头，写作「共享类型（目前是空 barrel）」而不是编一个用途。

零回退：PR #987 刚落地的 dashboards/, reports/, datasets/ 一行原样未动（diff 可见）。

边界：后缀表其余各行按 issue 边界不预判 —— 只删掉那一行幻影，*.dataset.ts / *.mapping.ts / *.seed.ts 等缺行不在本单范围内。树补缺项是因为 issue 的「缺项由 triage 定」已由派发裁定为「按 src/ 实况写实」；后缀表的「不预判」则是 issue 明写的边界，两者刻意不对称。src/ 零改动。

② 守卫：test/docs-drift.test.ts 扩面

两层盲区叠加，所以两条轴都补：

• 文件轴 —— 原 TREE_DOCS 只有 9 个维护者文档，content/docs 从不被看。新增 PRODUCT_TREE_DOCS（本页三语）走同一条 inline 断言。
• 形态轴 —— 原正则要求字面量 src/ 前缀，而目录树把前缀画掉了（├── agents/）。新增 treeSrcDirs() 解析 src/ 节点下的直接子项，TREE_DIAGRAM_DOCS 覆盖所有画树的文档：README.md、AGENTS.md、docs/README.md 以及本页三语（维护者文档的树此前同样看不见，只是今天恰好没有幻影）。

解析器同时吃两种根：维护者文档根在 hotcrm/（src/ 是一个树节点），产品文档根就是 src/ 本身（那一行没有分支符号）；一行画多个（apps/, views/, pages/）按逗号/空格拆；# 注释不算条目。

既有断言零语义变化：原 describe 的文件集、正则、断言与报错文案都没动，只是把那条正则抽成 inlineSrcDirs() 供两处共用。

防空转：两条新断言各带一条 vacuity 断言 —— 解析结果为空时报错退出，而不是「什么都没匹配到所以绿」。

为什么是白名单而不是遍历 content/docs：customization/ai-skills.mdx:10 正确地以否定式提到该路径（“there is no ... directory”），「列出即须存在」在任意产品散文上并不成立，所以按页逐个纳入。

两阶段红→绿验证

方向是开工前就定的：旧文档 + 新守卫应当红（页面确实画着不存在的目录），6 条（3 语 × 2 条新断言），既有断言全绿。实测与预判一致。

红（stash 掉三个 mdx 的改动，只留守卫）：

 FAIL  test/docs-drift.test.ts > product docs do not point at directories that no longer exist > content/docs/getting-started/for-developers.mdx: every src/ dir it names exists
 FAIL  ... for-developers.zh-Hans.mdx / .zh-Hant.mdx（同上）
 FAIL  test/docs-drift.test.ts > docs that draw the src/ tree only draw directories that exist > content/docs/getting-started/for-developers.mdx: every directory under its src/ node exists
 FAIL  ... for-developers.zh-Hans.mdx / .zh-Hant.mdx（同上）
AssertionError: ... draws src/ directories that do not exist: agents. ...: expected [ 'agents' ] to deeply equal []
 Test Files  1 failed (1)
      Tests  6 failed | 37 passed (43)

绿（恢复文档改动）：

 Test Files  1 passed (1)
      Tests  43 passed (43)

vacuity 反证（把树的制表符号换成 ASCII，模拟「树被重排、解析器失灵」）：

AssertionError: content/docs/getting-started/for-developers.mdx is listed as drawing a src/ tree,
but no entry was parsed under a src/ node. ...: expected 0 to be greater than 0
      Tests  1 failed | 5 passed | 37 skipped (43)

即解析不到就红，不会静默变绿。验证后已还原。

六道门（本地，串行在共享 verify lock 内）

门	退出码	关键行
pnpm validate	0	17 Objects / 24 Flows；仅既有 author-time 警告
pnpm typecheck	0	无输出
pnpm lint	0	13 warning(s), 14 suggestion(s)（皆既有）
pnpm hygiene	0	no raw control bytes in first-party files
pnpm build	0	Artifact: dist/objectstack.json (1921.3 KB)
pnpm test -- --maxWorkers=2	0	Test Files 75 passed / Tests 1766 passed, 1 skipped

控制字节：pnpm hygiene 的控制字节扫描覆盖 content 与 .changeset；另做自扫 grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]'，改动文件零命中。未起 dev server。

范围外发现

• customization/index 的 src/ 目录树与后缀表同样画着 #512 删掉的 agents/ 与 *.agent.ts（#984 的同型孪生页） #988 —— customization/index.{mdx,zh-Hans,zh-Hant} 的目录树与后缀表带着完全同型的 agents/ 与 *.agent.ts（该页树还缺 datasets/）。按 issue 边界不在本 PR 修；守卫的两个列表里已留注释指向 customization/index 的 src/ 目录树与后缀表同样画着 #512 删掉的 agents/ 与 *.agent.ts（#984 的同型孪生页） #988，那页修好后把三语加进列表即被覆盖。

---

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)
hotcrm	Ignored		Aug 6, 2026 3:05pm