1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | setup-ts-deep-modules |
| 作者/维护者 | Matt Pocock（Total TypeScript 创始人） |
| 来源链接 | https://github.com/mattpocock/skills/tree/main/skills/in-progress/setup-ts-deep-modules |
| 许可证 | MIT（数据来自 GitHub API） |
| GitHub Stars | 234,184（整个合集仓库层面，数据来自 GitHub API；该数字属整个仓库，不代表本技能自身热度） |
| Forks | 19,974（数据来自 GitHub API） |
| 最新版本 | 无独立版本号；该子技能目录最近一次实质提交 2026-08-19（数据来自 GitHub API） |
| 安装方式 | npx skills add https://github.com/mattpocock/skills --skill setup-ts-deep-modules |
2. 功能介绍与亮点
setup-ts-deep-modules 把一个 TypeScript 仓库里的每个 package 改造成“深模块”（deep module）：对外只暴露 package 根目录下的入口文件（可以有多个，如 index.ts、client.ts），实现细节一律藏进子文件夹（约定为 lib/），测试也只能经入口文件访问。核心是自动接入开源工具 dependency-cruiser，写入四条强制规则（入口边界、包内自由引用、测试只经入口、禁止循环依赖），再用一次“故意破坏规则 → 校验报红 → 撤销破坏 → 校验转绿”的闭环证明规则真的生效，而不是装了一个不会报错的摆设。
亮点：
- 可验证的完成标准：七个步骤逐一写明“Done when”判据，最后一步专门设计成“先看到失败，再看到恢复通过”，把“配置是否真的生效”这件事变成可复现的验证过程，而非一句自我声明。
- 不强推单一入口约定：允许一个 package 暴露多个入口文件，不强制“一个 index.ts 顶一切”的桶文件写法，并在文档里明确劝退桶文件（barrel file）。
- 接入已有配置不覆盖：若仓库已存在
.dependency-cruiser.*，技能会合并四条规则进去而不是整个覆盖，照顾到已有约定的团队。 - 随仓库同步维护
agents/openai.yaml适配文件，为 Codex 场景单独声明展示名与简介。
3. 适用场景
所属分类：工程效率与代码质量
适用于维护 TypeScript monorepo、且希望用可执行规则（而非代码评审口头约定）固定“包与包之间只能通过公开入口互相依赖”这条边界的团队或个人开发者。典型场景：多包仓库出现过“外部代码悄悄 import 了某个包 lib/ 内部实现文件”导致重构牵一发动全身的问题，希望装一次配置就能在 CI 里自动拦截同类回归。
4. 跨 Agent 兼容性
- Claude Code：原生支持 ✅。frontmatter 含
disable-model-invocation: true，需用户手动触发（如调用该技能名），不会被模型自动隐式调用。 - Codex：需适配 ⚠️。技能目录下带独立的
agents/openai.yaml（声明display_name/short_description，且显式设allow_implicit_invocation: false），是仓库为该技能专门维护的 Codex 支持证据；但仍需经通用安装器npx skills add安装，非官方一键插件。 - OpenClaw：未验证 ❓。第三方技能市场页面列出 OpenClaw 为通用安装器支持的目标平台之一，但未找到该技能与 OpenClaw 具体兼容性的独立说明。
- Hermes Agent：未验证 ❓。frontmatter 的
name/description满足 Hermes 规范必填项，但仓库未提供 Hermes 专属安装清单或适配文件，未找到已验证的兼容性说明。
5. 推荐理由
它把“包与包之间不许深层 import”这类常在代码评审里靠口头约定、容易被新成员或 AI 生成代码悄悄破坏的规则，变成一条 CI 会真的报红的机械闸门，且技能本身在收尾前会自证规则确实生效，避免装完就是一份不起作用的配置文件。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 8 | 第三方平台 skills.sh 显示该子技能安装量约 136,200 次；仓库整体 234,184 星不计入子技能个体热度；作者为个人开发者，无官方/机构背书加成 |
| 可用性 | 9 | 经通用安装器一条命令安装，随后由 agent 自动完成环境探测、配置写入、CI 接线与验证闭环；SKILL.md 七步骤均配“Done when”完成判据，附带示例 package 模板；该子技能路径最近一次实质提交 2026-08-19，维护活跃；无付费依赖 |
| 安全性 | 8 | 见下方检查清单 |
综合评分：8.33
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令与权限范围 | 会执行 npm install（写入 devDependency）、写入 .dependency-cruiser.cjs 配置文件、修改 package.json 的 script、运行 depcruise 校验，并短暂制造一次违规 import 再撤销以验证规则生效；每一步都在 SKILL.md 中写明目的与范围，无隐藏动作 |
| ② 联网外发 | 仅通过 npm 官方源下载 dependency-cruiser 这一个公开依赖包，无遥测、无用户数据外发 |
| ③ 凭据处理 | 不涉及任何 API key 或密钥 |
| ④ 可疑指令 | 通读 SKILL.md 全文未发现夹带无关推广、隐蔽外发或 prompt injection 迹象 |
| ⑤ 作者信誉 | 个人开发者 Matt Pocock，Total TypeScript 创始人，长期在 TypeScript 社区公开产出教学与工具内容，无刷星或虚假宣传记录 |
| ⑥ License | MIT，明确 |
| ⑦ 维护时间 | 该子技能路径最近一次实质提交 2026-08-19，活跃 |
该技能会真实执行包安装与仓库文件写入，作者为个人开发者、非官方或机构出品；执行范围明确、过程可审计、无不透明外联，整体风险可控。
7. 跟同类 Skills 相比的优势
| 技能 | 定位 | 与本技能的差异 |
|---|---|---|
| tdd（同一作者出品） | 红绿重构循环的测试驱动开发流程 | 关注“怎么写测试、怎么切片开发”，不涉及包与包之间的依赖边界；两者可配合使用，但解决的是不同层面的问题 |
| jest-skill（LambdaTest 出品） | 生成规范化的 Jest 单测/集成测试代码 | 聚焦“写出统一风格的测试断言与 Mock”，不涉及模块化架构约束；面向单文件测试产出，而非仓库级依赖规则 |
本技能的差异化在于：它不产出测试代码或开发流程指导，而是把“模块之间只能怎么互相依赖”这条架构约束，转成一份可被 CI 强制执行的静态规则，并自带验证闭环证明规则确实生效。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价；多个技能聚合站点收录了其 SKILL.md 内容，但均未附带独立评分或署名评论。
9. 其他补充
技能所属的 mattpocock/skills 仓库整体在开源社区有较高声量（第三方报道称该仓库上线 24 小时内获得约 2.2 万星、一度登上 GitHub Trending 全球第一），但该热度属于仓库整体，不代表本技能自身的独立采用程度。
10. 安装使用方式
- 通用安装器：
npx skills add https://github.com/mattpocock/skills --skill setup-ts-deep-modules - 安装后触发：需由用户主动调用该技能（frontmatter 声明
disable-model-invocation: true，不会被模型自动隐式触发） - 触发后 agent 会依次探测包管理器与 packages 根目录、安装 dependency-cruiser、写入/合并配置、接入 CI 检查脚本、生成示例 package、跑一次“破坏规则再恢复”的验证循环，并在 packages 目录写入说明文档
11. 注意事项
- 会真实修改仓库的
package.json（新增 devDependency 与 script）与写入新的配置文件，建议在版本控制下的干净工作区执行，便于必要时回退 - 若仓库已有
.dependency-cruiser.*配置，技能会尝试合并四条规则而非覆盖，但仍建议安装后人工检查一遍合并结果 - 该技能位于仓库的
in-progress目录，作者标注为迭代中状态，尚无独立文档页