深入 Effect TypeScript Monorepo：仓库布局、验证工作流与生成文件管理

深入 Effect TypeScript Monorepo：仓库布局、验证工作流与生成文件管理

【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect

本指南基于仓库根目录的 .agents/AGENTS.md（即项目根目录 AGENTS.md 的源文件）展开，系统讲解 Effect TypeScript 单体仓库（monorepo）的目录布局、为 AI Agent 与人类开发者设计的验证（Validation）工作流，以及生成文件（Generated Files）的管理规则。读完本文，你将掌握在该仓库中定位代码、选择最小化验证命令、安全修改代码并提交变更的完整方法。

说明：仓库根目录的AGENTS.md是由 scripts/setup-agents.mjs 通过符号链接指向.agents/AGENTS.md的，后者是权威源文件。该文件是项目面向 Agent 与贡献者的核心工程指南，本文以其为骨架，并结合根目录 package.json、vitest.config.ts、dprint.json、.changeset/config.json 等真实配置进行深化。

一、仓库定位：pnpm 驱动的 TypeScript 单体仓库

AGENTS.md 开篇即点明仓库的核心事实：

• 这是Effect TypeScript monorepo；
• Git 基础分支为main（与 .changeset/config.json 中的"baseBranch": "main"一致）；
• 所有命令统一在仓库根目录使用pnpm执行（根 package.json 声明"packageManager": "pnpm@11.20.0"，仓库通过 pnpm-workspace.yaml 管理多包工作区）。

从根 package.json 可以看到，prepare脚本会执行node scripts/setup-agents.mjs && effect-tsgo patch，其中 setup-agents.mjs 负责把.agents/AGENTS.md符号链接为根目录AGENTS.md。这意味着：当你看到根目录的 AGENTS.md 时，它实际指向.agents/AGENTS.md，任何更新都应作用于.agents/AGENTS.md。

二、仓库布局：核心代码、包族与文档源

AGENTS.md 的 Layout 小节给出了权威目录划分，结合实际仓库可以进一步细化：

各包族的实际形态（从源码结构看）：packages/ai下包含 anthropic、openai、openai-compat、openrouter 等 AI 集成包；packages/atom下包含 react、solid、vue 响应式绑定；packages/platform下包含 browser、bun、deno、node、node-shared 等平台实现；packages/sql下包含 clickhouse、d1、libsql、mssql、mysql2、pg、pglite、sqlite 系列等数据库驱动。

AGENTS.md 还强调了一条通用原则：编辑前先观察周边代码（Inspect nearby code before editing），即任何改动都应先阅读相邻源码与测试，遵循仓库内部约定——这与 .agents/skills/effect-development/SKILL.md 中"先查阅 LLMS.md 与 ai-docs/src 定位相关 API，再检查周边源码与测试"的工作流一脉相承。

三、验证工作流：按变更类型选择最小化验证

AGENTS.md 的核心是 Validation 小节：它要求开发者始终使用能覆盖本次变更的最窄验证方式，绝不跑全量测试。下表为原文表格的完整呈现：

3.1 关键命令在仓库中的真实含义

上述命令均可在根 package.json 中找到对应脚本：

• pnpm lint-fix：执行oxlint --fix && dprint fmt。oxlint 负责静态检查与自动修复，dprint 负责格式化（格式规则见 dprint.json，包含 TypeScript/Markdown/JSON 三个插件，缩进 2 空格、行宽 120）。
• pnpm test --run <test_file.ts>：test脚本为vitest。vitest.config.ts 将测试组织为多项目（project）运行：核心包packages/effect、AI 系列、atom 系列、platform 系列、sql 系列、tools 系列均注册为独立 vitest project，默认匹配test/**/*.test.{ts,tsx}。
• pnpm check：执行tsc -b tsconfig.json，即对整个 TypeScript 工程做构建级类型检查。
• pnpm test-types <filename>：test-types脚本为tstyche --target '>=5.9'。类型测试文件匹配规则见 tstyche.json（packages/*/typetest/**/*.tst.*等），使用baselinetsconfig。
• pnpm jsdocs --check：jsdocs脚本为effect-jsdocs，配置见 jsdocs.config.json（检查packages/**/src下的源码注释，排除 internal 与 Generated 文件，输出到.data/jsdocs.json）。
• pnpm doctest --run <files>：doctest脚本为vitest --config vitest.docs.ts。vitest.docs.ts 挂载@effect/doctest插件，通过includeSource扫描packages/*/src/**/*.ts中的可执行文档示例，保证 JSDoc 里的示例代码真实可运行。

3.2 为什么禁止裸跑pnpm test或pnpm doctest

AGENTS.md 明确警告：永远不要裸跑pnpm test或pnpm doctest——两者都会以 watch 模式启动全量测试套件（这正是 vitest 的默认行为）。正确做法是：

1. 始终传递--run（一次性运行而非监听）；
2. 始终指定覆盖本次变更的具体文件；
3. 全量套件由 CI 负责运行。

这一约束与 vitest.config.ts 中sequence: { concurrent: true }（测试并发执行）以及数十个 vitest project 的规模相印证：全量测试代价高昂，定向运行是仓库内协作的基本纪律。

3.3 临时验证沙箱：scratchpad

对于临时性的可运行探针（ad hoc runnable probe），AGENTS.md 给出的流程是：

1. 在 scratchpad 目录创建<name>.ts；
2. 用普通node运行它；
3. 完成后删除该文件。

从 scratchpad/package.json 可见，该目录预置了全部工作区依赖（effect、@effect/ai-*、@effect/platform-*、@effect/sql-*、@effect/opentelemetry等），因此可以零配置地引用任何仓库内包做快速实验，且不会污染正式源码。

此外，AGENTS.md 要求：报告任何无法执行的命令（Report any commands that could not be run），以保证协作透明、避免静默跳过验证。

四、生成文件管理：只改源头，不改产物

AGENTS.md 的 Generated Files 小节确立了"不直接编辑生成输出"的硬性规则：

1. @barrel标记的index.ts段：部分index.ts中标记为@barrel的段是生成代码，禁止手工编辑。正确做法是修改对应的源模块，然后运行pnpm codegen（根脚本会通过pnpm --recursive --parallel对packages/**/*递归执行各包的 codegen，如packages/effect的effect-utils codegen）。
2. 手工维护的index.ts与未标记段落：不适用该规则，可正常编辑。
3. LLMS.md与migration/v3-to-v4.md：
   • LLMS.md 由 ai-docs/src 生成（对应根脚本ai-docgen：effect-ai-docgen ai-docs/src -o LLMS.md，另有ai-docgen:watch监听模式）；
   • migration/v3-to-v4.md 由 migration/annotations 生成。
4. 第三方资产：已签入的第三方资产必须通过其生成器或文档化的导入流程更新，不得直接改动。

这条规则的意义在于保持产物与源的一致性：任何对生成文件的直接修改都会在下次 codegen 时被覆盖，造成漂移（drift）。

五、配套的 Agent 技能体系

.agents目录不仅是 AGENTS.md 的所在地，还内置了一套面向 AI Agent 的技能（skill）定义，与本文工作流配合使用：

• effect-development：Effect API 组合与代码评审指引；
• test-development 与 jsdocs：测试开发与 JSDoc 规范；
• migration-guidance：v3 → v4 迁移指南；
• changesets、ci-maintenance、dependency-maintenance、performance-analysis、bundle-analysis 等。

这些技能与 AGENTS.md 共同构成了 Agent 在本仓库工作的"操作手册"，其中反复强调的做法与 AGENTS.md 一致：以仓库文档为定向参考而非全量上下文，先定位相关 API 与测试，再动手修改。

六、实战检查清单

综合全文，一次符合规范的仓库变更应遵循以下步骤：

1. 定位：在 packages/effect/src（或其他包族）找到相关源码，阅读 packages/effect/test 与 packages/effect/typetest 中相邻测试，理解仓库内部约定；
2. 判断变更类型：对照本文第三节的验证表格，确定本次变更属于代码 / 测试 / 类型 / JSDoc / 纯文档中的哪一类；
3. 执行最小化验证：运行对应的pnpm lint-fix、定向pnpm test --run <file>、pnpm test-types <filename>、pnpm jsdocs --check或pnpm doctest --run <files>，绝不在本地跑裸pnpm test；
4. 处理生成文件：若涉及@barrel段、LLMS.md或迁移文档，只修改源文件后运行pnpm codegen/pnpm ai-docgen重新生成；
5. 快速实验：临时逻辑放入 scratchpad，用node验证后删除；
6. 记录变更：通过 .changeset 添加变更集（版本与发布由 changesets 流程管理，见 .changeset/config.json 的 fixed 包组配置），并报告任何无法执行的命令。

这套流程既是人类贡献者的工程纪律，也是 AI Agent 在本仓库安全产出代码的行为准则——理解它，你就掌握了进入 Effect TypeScript 生态开发的第一把钥匙。

【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect