尧图网页设计 
深入 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 monorepoGit 基础分支为main与 .changeset/config.json 中的baseBranch: main一致所有命令统一在仓库根目录使用pnpm执行根 package.json 声明packageManager: pnpm11.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/effect/src、packages/effect/test、packages/effect/typetest核心库源码、运行时测试、类型测试packages/ai、packages/atom、packages/platform、packages/sql、packages/tools其他包族独立包也直接位于packages下如 packages/opentelemetry、packages/vitest各包内的test、typetest目录与源码并列存放的测试与类型测试ai-docs/srcAI 文档源用于生成 LLMS.md.changesetChangesets 变更集migration/annotationsv3 → v4 迁移标注源各包族的实际形态从源码结构看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 小节它要求开发者始终使用能覆盖本次变更的最窄验证方式绝不跑全量测试。下表为原文表格的完整呈现变更类型验证命令代码变更Code changespnpm lint-fix、定向pnpm test --run test_file.ts、pnpm check仅测试变更Tests-only changespnpm lint-fix、定向pnpm test --run test_file.ts、pnpm check类型层 / API 类型变更Type-level/API type changes定向pnpm test-types filename若源码类型有变再加pnpm checkJSDoc 文本 / 分类 / 链接变更pnpm jsdocs --check、pnpm lintJSDoc 示例变更pnpm jsdocs --check、pnpm lint、根目录pnpm doctest --run files仅文档变更Docs-only changespnpm lint-fix除非示例或代码有变否则无需跑测试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.tstest脚本为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 filenametest-types脚本为tstyche --target 5.9。类型测试文件匹配规则见 tstyche.jsonpackages/*/typetest/**/*.tst.*等使用baselinetsconfig。pnpm jsdocs --checkjsdocs脚本为effect-jsdocs配置见 jsdocs.config.json检查packages/**/src下的源码注释排除 internal 与 Generated 文件输出到.data/jsdocs.json。pnpm doctest --run filesdoctest脚本为vitest --config vitest.docs.ts。vitest.docs.ts 挂载effect/doctest插件通过includeSource扫描packages/*/src/**/*.ts中的可执行文档示例保证 JSDoc 里的示例代码真实可运行。3.2 为什么禁止裸跑pnpm test或pnpm doctestAGENTS.md 明确警告永远不要裸跑pnpm test或pnpm doctest——两者都会以 watch 模式启动全量测试套件这正是 vitest 的默认行为。正确做法是始终传递--run一次性运行而非监听始终指定覆盖本次变更的具体文件全量套件由 CI 负责运行。这一约束与 vitest.config.ts 中sequence: { concurrent: true }测试并发执行以及数十个 vitest project 的规模相印证全量测试代价高昂定向运行是仓库内协作的基本纪律。3.3 临时验证沙箱scratchpad对于临时性的可运行探针ad hoc runnable probeAGENTS.md 给出的流程是在 scratchpad 目录创建name.ts用普通node运行它完成后删除该文件。从 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 小节确立了不直接编辑生成输出的硬性规则barrel标记的index.ts段部分index.ts中标记为barrel的段是生成代码禁止手工编辑。正确做法是修改对应的源模块然后运行pnpm codegen根脚本会通过pnpm --recursive --parallel对packages/**/*递归执行各包的 codegen如packages/effect的effect-utils codegen。手工维护的index.ts与未标记段落不适用该规则可正常编辑。LLMS.md与migration/v3-to-v4.mdLLMS.md 由 ai-docs/src 生成对应根脚本ai-docgeneffect-ai-docgen ai-docs/src -o LLMS.md另有ai-docgen:watch监听模式migration/v3-to-v4.md 由 migration/annotations 生成。第三方资产已签入的第三方资产必须通过其生成器或文档化的导入流程更新不得直接改动。这条规则的意义在于保持产物与源的一致性任何对生成文件的直接修改都会在下次 codegen 时被覆盖造成漂移drift。五、配套的 Agent 技能体系.agents目录不仅是 AGENTS.md 的所在地还内置了一套面向 AI Agent 的技能skill定义与本文工作流配合使用effect-developmentEffect API 组合与代码评审指引test-development 与 jsdocs测试开发与 JSDoc 规范migration-guidancev3 → v4 迁移指南changesets、ci-maintenance、dependency-maintenance、performance-analysis、bundle-analysis 等。这些技能与 AGENTS.md 共同构成了 Agent 在本仓库工作的操作手册其中反复强调的做法与 AGENTS.md 一致以仓库文档为定向参考而非全量上下文先定位相关 API 与测试再动手修改。六、实战检查清单综合全文一次符合规范的仓库变更应遵循以下步骤定位在 packages/effect/src或其他包族找到相关源码阅读 packages/effect/test 与 packages/effect/typetest 中相邻测试理解仓库内部约定判断变更类型对照本文第三节的验证表格确定本次变更属于代码 / 测试 / 类型 / JSDoc / 纯文档中的哪一类执行最小化验证运行对应的pnpm lint-fix、定向pnpm test --run file、pnpm test-types filename、pnpm jsdocs --check或pnpm doctest --run files绝不在本地跑裸pnpm test处理生成文件若涉及barrel段、LLMS.md或迁移文档只修改源文件后运行pnpm codegen/pnpm ai-docgen重新生成快速实验临时逻辑放入 scratchpad用node验证后删除记录变更通过 .changeset 添加变更集版本与发布由 changesets 流程管理见 .changeset/config.json 的 fixed 包组配置并报告任何无法执行的命令。这套流程既是人类贡献者的工程纪律也是 AI Agent 在本仓库安全产出代码的行为准则——理解它你就掌握了进入 Effect TypeScript 生态开发的第一把钥匙。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 深入 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 monorepoGit 基础分支为main与 .changeset/config.json 中的baseBranch: main一致所有命令统一在仓库根目录使用pnpm执行根 package.json 声明packageManager: pnpm11.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/effect/src、packages/effect/test、packages/effect/typetest核心库源码、运行时测试、类型测试packages/ai、packages/atom、packages/platform、packages/sql、packages/tools其他包族独立包也直接位于packages下如 packages/opentelemetry、packages/vitest各包内的test、typetest目录与源码并列存放的测试与类型测试ai-docs/srcAI 文档源用于生成 LLMS.md.changesetChangesets 变更集migration/annotationsv3 → v4 迁移标注源各包族的实际形态从源码结构看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 小节它要求开发者始终使用能覆盖本次变更的最窄验证方式绝不跑全量测试。下表为原文表格的完整呈现变更类型验证命令代码变更Code changespnpm lint-fix、定向pnpm test --run test_file.ts、pnpm check仅测试变更Tests-only changespnpm lint-fix、定向pnpm test --run test_file.ts、pnpm check类型层 / API 类型变更Type-level/API type changes定向pnpm test-types filename若源码类型有变再加pnpm checkJSDoc 文本 / 分类 / 链接变更pnpm jsdocs --check、pnpm lintJSDoc 示例变更pnpm jsdocs --check、pnpm lint、根目录pnpm doctest --run files仅文档变更Docs-only changespnpm lint-fix除非示例或代码有变否则无需跑测试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.tstest脚本为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 filenametest-types脚本为tstyche --target 5.9。类型测试文件匹配规则见 tstyche.jsonpackages/*/typetest/**/*.tst.*等使用baselinetsconfig。pnpm jsdocs --checkjsdocs脚本为effect-jsdocs配置见 jsdocs.config.json检查packages/**/src下的源码注释排除 internal 与 Generated 文件输出到.data/jsdocs.json。pnpm doctest --run filesdoctest脚本为vitest --config vitest.docs.ts。vitest.docs.ts 挂载effect/doctest插件通过includeSource扫描packages/*/src/**/*.ts中的可执行文档示例保证 JSDoc 里的示例代码真实可运行。3.2 为什么禁止裸跑pnpm test或pnpm doctestAGENTS.md 明确警告永远不要裸跑pnpm test或pnpm doctest——两者都会以 watch 模式启动全量测试套件这正是 vitest 的默认行为。正确做法是始终传递--run一次性运行而非监听始终指定覆盖本次变更的具体文件全量套件由 CI 负责运行。这一约束与 vitest.config.ts 中sequence: { concurrent: true }测试并发执行以及数十个 vitest project 的规模相印证全量测试代价高昂定向运行是仓库内协作的基本纪律。3.3 临时验证沙箱scratchpad对于临时性的可运行探针ad hoc runnable probeAGENTS.md 给出的流程是在 scratchpad 目录创建name.ts用普通node运行它完成后删除该文件。从 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 小节确立了不直接编辑生成输出的硬性规则barrel标记的index.ts段部分index.ts中标记为barrel的段是生成代码禁止手工编辑。正确做法是修改对应的源模块然后运行pnpm codegen根脚本会通过pnpm --recursive --parallel对packages/**/*递归执行各包的 codegen如packages/effect的effect-utils codegen。手工维护的index.ts与未标记段落不适用该规则可正常编辑。LLMS.md与migration/v3-to-v4.mdLLMS.md 由 ai-docs/src 生成对应根脚本ai-docgeneffect-ai-docgen ai-docs/src -o LLMS.md另有ai-docgen:watch监听模式migration/v3-to-v4.md 由 migration/annotations 生成。第三方资产已签入的第三方资产必须通过其生成器或文档化的导入流程更新不得直接改动。这条规则的意义在于保持产物与源的一致性任何对生成文件的直接修改都会在下次 codegen 时被覆盖造成漂移drift。五、配套的 Agent 技能体系.agents目录不仅是 AGENTS.md 的所在地还内置了一套面向 AI Agent 的技能skill定义与本文工作流配合使用effect-developmentEffect API 组合与代码评审指引test-development 与 jsdocs测试开发与 JSDoc 规范migration-guidancev3 → v4 迁移指南changesets、ci-maintenance、dependency-maintenance、performance-analysis、bundle-analysis 等。这些技能与 AGENTS.md 共同构成了 Agent 在本仓库工作的操作手册其中反复强调的做法与 AGENTS.md 一致以仓库文档为定向参考而非全量上下文先定位相关 API 与测试再动手修改。六、实战检查清单综合全文一次符合规范的仓库变更应遵循以下步骤定位在 packages/effect/src或其他包族找到相关源码阅读 packages/effect/test 与 packages/effect/typetest 中相邻测试理解仓库内部约定判断变更类型对照本文第三节的验证表格确定本次变更属于代码 / 测试 / 类型 / JSDoc / 纯文档中的哪一类执行最小化验证运行对应的pnpm lint-fix、定向pnpm test --run file、pnpm test-types filename、pnpm jsdocs --check或pnpm doctest --run files绝不在本地跑裸pnpm test处理生成文件若涉及barrel段、LLMS.md或迁移文档只修改源文件后运行pnpm codegen/pnpm ai-docgen重新生成快速实验临时逻辑放入 scratchpad用node验证后删除记录变更通过 .changeset 添加变更集版本与发布由 changesets 流程管理见 .changeset/config.json 的 fixed 包组配置并报告任何无法执行的命令。这套流程既是人类贡献者的工程纪律也是 AI Agent 在本仓库安全产出代码的行为准则——理解它你就掌握了进入 Effect TypeScript 生态开发的第一把钥匙。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考