setup-ts-deep-modules
把 dependency-cruiser 接入 TypeScript 仓库,让每个包都成为深模块,实现隐藏在子文件夹中,只能通过入口文件触达。用户调用。
- License 许可
- MIT
- 最近更新
- 2026-10-19
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- setup-ts-deep-modules
- description
- 把 dependency-cruiser 接入 TypeScript 仓库,让每个包都成为深模块,实现隐藏在子文件夹中,只能通过入口文件触达。用户调用。
- commit_version
- 321658273cb1d20b76026717d027d505790106d4
- disable-model-invocation
- true
02 资源文件 2
- 参考文档agents/openai.yaml145 B
- 脚本dependency-cruiser.config.cjs3.6 KB
03 SKILL.md 正文
设置 TS 深模块
让本仓库中的每个包都成为深模块(deep module):小接口背后藏着大量行为。包的公开表面是它的入口点(entry points)(包根目录下的文件),子文件夹中的一切都是隐藏的。本技能安装 dependency-cruiser 以及让入口点成为唯一入口的规则,然后证明这些规则真的会咬人。
相关词汇(deep module、interface、seam、depth),调用 Skill 工具并传入 "codebase-design",全程使用它的语言。
这要强制的形状
src/packages/
<name>/
index.ts ← 一个入口点(公开)。从外部 import 它。
client.ts ← 另一个入口点。包可以暴露多个。
lib/ ← 实现:对外隐藏,内部互相 import 自由。
tests/ ← 同放一处的测试 + fixture(是子文件夹,所以是私有的)。
公开表面是包的根文件,而不是某个指定的 index.ts。按约定实现放在 lib/、测试放在 tests/,让每个包都有同样的双文件夹形状。但规则本身是通用的:任何子文件夹中的任何东西都是私有的,所以你永远不需要为了加一个文件夹而扩展配置。
四条规则,全部为 error:
- 入口点边界:包外的代码(应用代码或另一个包)只能 import 该包的入口点(它的根文件),永远不能 import 其子文件夹中的任何东西。
- 包内自由:包自己的文件之间可以自由互相 import。
- 测试走入口点:
<pkg>/tests/下的文件可以 import 任何包的入口点和它们自己tests/的 fixture,但永远不能 import 任何包的子文件夹内部实现(包括它们自己的)。跨包的集成测试没问题;深 import 不行。 - 禁止循环:不允许依赖循环。
入口点,而不是 barrel。 因为公开表面是每一个根文件,一个包可以暴露若干个小入口点(index.ts、client.ts、server.ts),而不是把一切都漏斗式地塞进一个巨大的 index.ts。不鼓励 re-export 整个子树的 barrel 文件;保持入口点小而把实现藏进子文件夹。
分层(哪些包可以依赖哪些包)是另一个关注点,在配置中以注释掉的存根留给本仓库填写。
步骤
1. 检测环境
- 包管理器:
pnpm-lock.yaml→ pnpm,yarn.lock→ yarn,bun.lockb→ bun,否则 npm。下面每条命令都用它(pnpm/yarn/npm run/bunx)。 - 包根目录:如果
src/存在就用src/packages,否则用packages。如果仓库已有其他明显约定,与用户确认选择。 - 现有配置:检查是否有
.dependency-cruiser.*文件。如果存在,不要覆盖它:把四条规则和选项合并进去,并告诉用户你添加了什么。
完成标准: 包管理器、包根目录和现有配置状态都已知。
2. 安装 dependency-cruiser
用检测到的包管理器把 dependency-cruiser 安装为 devDependency。
完成标准: dependency-cruiser 在 devDependencies 中。
3. 写配置
把 dependency-cruiser.config.cjs 复制到仓库根目录,命名为 .dependency-cruiser.cjs。把 PACKAGES_ROOT 设为第 1 步检测到的根目录。规则基于路径深度、与扩展名无关,所以不需要其他适配。
完成标准: .dependency-cruiser.cjs 存在且 PACKAGES_ROOT 正确,四条 forbidden 规则都在。
4. 接入检查流程
- 添加
lint:boundaries脚本:depcruise <packages-root>(或depcruise src)。 - 把它并入仓库的总检查命令,即那个已经在跑 typecheck 的命令(例如
check/ci/validate脚本)。不要动tsconfig,不要加路径别名。 - 如果没有总检查脚本,添加
lint:boundaries并告诉用户把它纳入 CI。
完成标准: lint:boundaries 存在,并作为与 typecheck 相同的命令的一部分运行。
5. 搭建示例包
创建一个提交的 <packages-root>/example/ 作为可复制模板:
index.ts是一个入口点。导出一个委托给内部文件的函数(让这个包 visibly 深,而不是直通转发)。lib/impl.ts:子文件夹中的内部文件,被index.tsimport,从外部不可达。tests/example.test.ts只 import../index(一个入口点),并对公开函数做断言。
告诉用户这是一个可以复制或删除的起始模板。
完成标准: 示例包存在,通过根入口点暴露其行为,并把 impl 藏在子文件夹中。
6. 证明规则会咬人
这是整个技能的完成标准:一个对违规不失败的配置毫无价值。
- 运行
lint:boundaries。在干净的示例上它必须通过。 - 临时向
tests/example.test.ts添加一个深 import(例如import { thing } from "../lib/impl")。再次运行lint:boundaries;它必须以tests-through-entrypoints失败。 - 还原这个深 import。再运行一次,它必须通过。
完成标准: 你观察到了一次通过,然后深 import 失败,然后再次通过。如果第 2 步没有失败,说明规则没有接对,所以修好再收尾。
7. 记录约定
在包文件夹中(<packages-root>/README.md,放在它管辖的包旁边)写一份 README.md,覆盖:src/packages/<name>/ 布局(入口点在根部,lib/ 放实现,tests/ 放测试)、"只能通过包的入口点(它的根文件)import",以及如何运行 lint:boundaries。明确不鼓励 barrel 文件:暴露若干小入口点,而不是通过一个 index re-export 整个子树。内容保持为可复制片段加上四条规则各一段话。
然后从仓库的 agent 指示文件添加一个上下文指针指向它(有 CLAUDE.md 就用它,否则用 AGENTS.md,两者都不存在就创建 AGENTS.md)。一行就够,例如 Packages are deep modules: see [src/packages/README.md](./src/packages/README.md) before adding or importing one. 这正是让 agent 发现边界规则而不是被它绊倒的东西。
完成标准: <packages-root>/README.md 存在且不鼓励 barrel,且仓库的 CLAUDE.md/AGENTS.md 链接到它。
备注
- 配置的
$1反向引用(dependency-cruiser 的分组匹配)是让包能触达自己内部而外部不能的关键。不要把它们展开成逐包的独立规则。 - 公开还是私有由深度决定:包的根文件是入口点;子文件夹中的任何东西都是私有的。约定俗成的子文件夹是
lib/(实现)和tests/,但规则并不硬编码它们:任何子文件夹都是私有的,所以新文件夹永远不需要改配置。添加入口点就是添加一个根文件(不需要 barrel)。 - 包是扁平的:根目录下只有一层直接子级。包的内部想嵌套多深都行;包不能包含另一个包。
- 用
.cjs(而不是.js),这样配置的module.exports在"type": "module"的仓库中也能工作。
04 同仓库更多 Skills
skills-link
管理 muscaestar/skills 仓库的 skill 安装。当用户想安装/卸载某个 skill、查看已装清单、把 skill 装到全局或某个项目、或问"这个 skill 装了没有"时使用。也用于向用户解释三层结构与全局/项目双范围安装策略。
writing-shape
写作之 exploit:把原始素材塑形成一篇文章,逐段进行。
writing-fragments
写作之 explore:开采原始碎片,还没有结构。
writing-for-agents
为 agents 编写文档。在创建或编辑技能,或修改 AGENTS.md 或 CLAUDE.md 时使用。
writing-beats
写作之 exploit;把原始素材组装成一段由节拍(beat)构成的旅程,在每个节拍倚赖某个术语之前先把它落地。
wizard
生成一个交互式 bash 向导,引导人类完成只有他们才能执行的步骤。当需要配置基础设施、设置凭据或 CI secret、摸索不熟悉的第三方仪表盘,或执行一次性的迁移或切换时使用。不要为 agent 自己能执行的步骤调用本技能。