setup-ts-deep-modules
将 dependency-cruiser 接入 TypeScript 仓库,使每个包都成为深模块——实现隐藏在子文件夹中,只能通过入口点文件访问。用户调用。
- License 许可
- MIT
- 最近更新
- 2026-07-23
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- setup-ts-deep-modules
- description
- 将 dependency-cruiser 接入 TypeScript 仓库,使每个包都成为深模块——实现隐藏在子文件夹中,只能通过入口点文件访问。用户调用。
- disable-model-invocation
- true
02 资源文件 2
- 参考文档agents/openai.yaml149 B
- 脚本dependency-cruiser.config.cjs3.6 KB
03 SKILL.md 正文
设置 TS 深模块
让本仓库中的每个包都成为深模块:以小接口承载大量行为。包的公共表面是其入口点——包根目录中的文件——而子文件夹中的一切都被隐藏。本技能会安装 dependency-cruiser,配置使入口点成为唯一进入方式的规则,然后证明这些规则确实会生效。
要获取相关词汇(深模块、接口、接缝、深度),请运行 /codebase-design 技能——全程使用其中的语言。
强制采用的形态
src/packages/
<name>/
index.ts ← 入口点(公开)。包外从这里导入。
client.ts ← 另一个入口点。包可以暴露多个入口点。
lib/ ← 实现:对外隐藏,内部可相互导入。
tests/ ← 同位置的测试和夹具(位于子文件夹,因此私有)。
公共表面是包的根文件——而不是某个指定的 index.ts。按照约定,实现位于 lib/ 中,测试位于 tests/ 中,使每个包都采用相同的双文件夹形态。不过规则本身是通用的:任意子文件夹中的任何内容都是私有的,因此绝不需要为了添加文件夹而扩展配置。
四条规则,严重性均为 error:
- 入口点边界——包外代码(应用代码或其他包)只能导入该包的入口点(根文件),绝不能导入其子文件夹中的任何内容。
- 包内自由——包自己的文件可以自由地相互导入。
- 通过入口点测试——
<pkg>/tests/下的文件可以导入任意包的入口点和自身的tests/夹具,但绝不能导入任何包的子文件夹内部内容(甚至自己的也不行)。允许跨包集成测试;不允许深层导入。 - 无循环——不得存在依赖循环。
使用入口点,而不是桶文件。 由于公共表面是每个根文件,因此包可以暴露若干小型入口点(index.ts、client.ts、server.ts),而不是让所有内容都通过一个庞大的 index.ts 汇聚。不鼓励使用重新导出整个子树的桶文件——入口点应保持小巧,实现则隐藏在子文件夹中。
分层(哪些包可以依赖哪些包)是另一项关注点;配置中为其保留了带注释的桩,由本仓库自行填写。
步骤
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 正确,并且包含四条禁止规则。
4. 接入检查
- 添加
lint:boundaries脚本:depcruise <packages-root>(或depcruise src)。 - 将其纳入仓库的综合检查命令——即已经运行类型检查的命令(例如
check/ci/validate脚本)。不得修改tsconfig,也不得添加路径别名。 - 如果没有综合脚本,则添加
lint:boundaries,并告诉用户将其纳入 CI。
完成标准: lint:boundaries 存在,并与类型检查作为同一命令的一部分运行。
5. 搭建示例包脚手架
创建并提交 <packages-root>/example/,作为可复制模板:
index.ts——入口点。导出一个委派给内部文件的函数(让包明显是深的,而不是透传层)。lib/impl.ts——位于子文件夹中的内部文件,由index.ts导入,无法从外部访问。tests/example.test.ts——仅导入../index(入口点),并针对公共函数进行断言。
告诉用户这是可以复制或删除的起始模板。
完成标准: 示例包存在,通过根入口点暴露其行为,并将 impl 隐藏在子文件夹中。
6. 证明规则确实生效
这是整个技能的完成标准——无法在违规时失败的配置毫无价值。
- 运行
lint:boundaries。它必须在干净的示例上通过。 - 临时向
tests/example.test.ts添加深层导入(例如import { thing } from "../lib/impl")。再次运行lint:boundaries——它必须失败,并给出tests-through-entrypoints。 - 撤销深层导入。再次运行——它必须通过。
完成标准: 你已观察到先通过,再因深层导入而失败,最后再次通过。如果步骤 2 没有失败,说明规则接入不正确——必须在完成前修复。
7. 记录约定
编写 README.md,并将它放在包文件夹中(<packages-root>/README.md)——紧邻它所管辖的包——涵盖:src/packages/<name>/ 布局(入口点位于根目录、lib/ 存放实现、tests/ 存放测试)、“仅通过包的入口点(根文件)导入”,以及如何运行 lint:boundaries。明确不鼓励使用桶文件——应当暴露若干小型入口点,而不是通过单个 index 重新导出整个子树。内容限制为可复制片段,并让四条规则每条各用一个段落说明。
然后从仓库的智能体指令文件添加指向它的上下文指针——如果 CLAUDE.md 存在则使用它,否则使用 AGENTS.md(如果两者都不存在,则创建 AGENTS.md)。一行即可,例如:包采用深模块设计——添加或导入包之前,请参阅 [src/packages/README.md](./src/packages/README.md)。这样智能体才能主动发现边界规则,而不是被规则绊倒。
完成标准: <packages-root>/README.md 已存在并明确不鼓励使用桶文件,而且仓库的 CLAUDE.md/AGENTS.md 已链接到该文件。
说明
- 配置中的
$1反向引用(dependency-cruiser 的分组匹配)使包能够访问自身内部内容,同时禁止外部访问——不要将它们展开成逐包独立规则。 - 公共与私有由深度决定:包的根文件是入口点;子文件夹中的任何内容都是私有的。约定的子文件夹是
lib/(实现)和tests/,但规则并未将它们硬编码——任何子文件夹都是私有的,因此新文件夹绝不需要修改配置。添加入口点只需添加根文件——无需桶文件。 - 包是扁平的:根目录下只有一层直接子目录。包的内部结构可以任意深地嵌套;包不能包含另一个包。
- 使用
.cjs(而不是.js),使配置的module.exports即使在"type": "module"仓库中也能工作。
04 同仓库更多 Skills
writing-great-skills
出色编写和编辑技能的参考资料——让技能具备可预测性的词汇与原则。
teach
在此工作区内向用户教授新的技能或概念。
handoff
将当前对话压缩成交接文档,以便另一个智能体接手。
grilling
围绕计划、决策或想法对用户进行不留情面的深度追问。当用户想对自己的思路进行压力测试,或使用任何“深度追问”触发措辞时使用。
grill-me
通过不留情面的深度追问打磨计划或设计。
obsidian-vault
使用 wikilink 和索引笔记搜索、创建和管理 Obsidian 仓库中的笔记。当用户想要在 Obsidian 中查找、创建或整理笔记时使用。