src/utils/ 是杂物抽屉：四类互不相关的职责挤在一个命名空间，含 387 行只有 scripts 用的构建工具

[SongshGeo]

src/utils/ 现在有 18 个文件、2,654 行，装着四类彼此不调用的东西。它不是一个
模块，是一个命名空间；「放哪儿」这个问题在这里没有答案，所以新代码永远落在这。

四个互不相交的簇

按 import 图划分，src/utils/ 里的文件分成四组，组间几乎没有边：

簇	文件	谁在用
Markdown 管线	obsidian-links.js remark-obsidian-callouts.js remark-revive-directives.js rehype-callouts.js render-markdown.js	只有 astro.config.mjs（配置加载期）和 newsLoader
Vault 布局 / 文件系统	contentLayout.js bundleAssets.js peopleIndex.ts libraryEntries.ts	loaders、页面、scripts
双语契约	localized.ts i18nContract.js siteConfig.ts	页面 / 只有 scripts / 页面
领域与展示	roles.ts relations.ts pageRelations.ts libraryTree.ts entrySlug.ts formatDate.ts	页面、React 组件

两个具体的错位：

• i18nContract.js（387 行，全仓最大的 util）在 src/ 下没有任何 importer。
  它只被 scripts/check-content.mjs、scripts/i18n-manifest.mjs、
  scripts/migrate-bundles.mjs 和它自己的测试 import。这是构建工具，住在站点
  源码目录里。它的文件头注释也自己说了：三个 consumer 都是 scripts 和一份 doc。

• 五个 remark/rehype 插件（710 行）没有一个页面 import。 它们的唯一消费者是
  astro.config.mjs，运行在 astro:content 存在之前。这是构建期插件，和
  formatDate.ts 这种被 React 岛 import 的东西放在同一个抽屉里。

后果不只是「不好看」

页面为了拼出一个条目，要从这个抽屉里挑 5–8 个名字（见另一个 issue）。因为没有
索引、没有分组，挑哪几个只能靠读源码。这也是为什么同一个事实会存四份
（#42）——第二个人不知道第一个人把它放哪了。

../../../ 已经 113 处

tsconfig.json 没有配 paths，所以 src/pages/[lang]/*/[slug].astro 里全是：

import { entrySlug } from '../../../utils/entrySlug';
import { COLLECTION_VAULT_PATHS } from '../../../utils/contentLayout.js';
import { coverFor } from '../../../utils/bundleAssets.js';

grep -rno '\.\./\.\./\.\./' src --include='*.astro' --include='*.tsx' | wc -l → 113。
目录一动，113 处要跟着动，而这正是下面建议要做的事——所以别名应该先加。

建议

1. 先加 tsconfig.json 的 paths（@/* → src/*）和 astro.config.mjs 的
   vite.resolve.alias，把 113 处相对路径收掉。这一步独立，不改任何语义。
2. 再按簇拆目录：
   • src/markdown/ ← 五个 remark/rehype 插件 + render-markdown.js
   • src/content-layer/ ← contentLayout bundleAssets peopleIndex
libraryEntries + 现有的 loaders/
   • src/i18n/ ← 已有 ui.ts，并入 localized.ts siteConfig.ts
   • src/domain/ ← roles relations pageRelations libraryTree
entrySlug formatDate
   • tools/ 或 scripts/lib/ ← i18nContract.js（它服务的是 scripts，
     不是站点）
3. 每个目录写一个 index.ts 作为对外的那一个入口，页面只 import 目录，不 import
   目录里的具体文件。

拆完之后「这段代码放哪」这个问题有答案了，src/utils/ 应当为空并删除。

[SongshGeo]

已实现（尚未提交，工作区待审）。

分两步，第一步单独可回滚：

1. @/ 别名（tsconfig.paths）。src/pages/、src/components/、src/layouts/ 里 151 处相对引用改成别名，../../../ 从 113 处降到 0。

四个层自己不用别名，这是个硬约束而不是风格选择：scripts/*.mjs 用纯 Node 跑，解析不了 tsconfig 别名，而它们直接 import contentLayout.js / contract.js / peopleIndex.ts / roles.ts。理由写在 tsconfig.json 的注释里。

2. 按依赖方向拆目录，src/utils/ 已删除：

src/content-layer/   contentLayout · bundleAssets · peopleIndex · libraryEntries · entrySlug
src/i18n/            ui · localized · contract        （原 i18nContract.js）
src/markdown/        obsidian-links · remark-* · rehype-callouts · render-markdown
src/domain/          relations · pageRelations · roles · libraryTree · formatDate
                     · siteConfig · routes · localizedPages

实测的层间边，无环：

content-layer  -> （无）
i18n           -> content-layer
markdown       -> content-layer
domain         -> content-layer, i18n
content        -> content-layer, domain, markdown
components     -> domain, i18n
layouts        -> components, i18n
pages          -> 以上全部

entrySlug 放进 content-layer 而不是 domain，是为了让 content-layer 真正成为叶子——否则 peopleIndex → entrySlug → domain → content-layer 就成环了。

没有加 barrel index.ts，虽然 issue 里我建议过。理由：roles.ts 和 types.ts 被 React 岛 import，barrel 会把同目录里无关的模块拖进客户端 bundle；别名已经让路径够短了。

README 加了一节 “Source layout” 画出这张层次图并说明为什么四个层不用别名。

验证：全流水线绿；构建出的 46 页在归一化 astro-island 的 uid 哈希后与基线完全一致（uid 由模块 id 派生，改目录必然变）。