Effect 仓库包开发实操指南把新增、重命名与移动工作区包当作注册变更来落地【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect导读本指南基于 Effect 仓库维护流程文档 .agents/skills/package-development/SKILL.md 及其配套的 依赖角色说明、注册面清单 与 发布审计流程系统讲解在 Effect 这个 pnpm monorepo 中正确新增一个工作区包、将私有包转为可发布包、以及重命名或移动包路径的标准流程。读完本文你将掌握一条可复用的七步工作流从审视同族包、起草依赖清单到逐项核对仓库注册面、验证打包产物最终以 changeset 收尾——每一步都能在当前仓库中找到真实的配置文件与实现证据作为对照。核心方法论包开发是注册变更不是目录拷贝SKILL.md 开篇给出了整个流程的锚点Treat package work as a registration change, not a directory copy.把包开发当作一次注册变更而不是一次目录拷贝。这句话的工程含义是在 Effect 这类多包仓库中新增一个包并不只是把src/、test/、package.json拷进packages/目录那么简单。一个包只有在被 pnpm workspace、TypeScript project references、vitest、tstyche、doctest、JSDoc、changeset、发布脚本等注册面registration surface全部认可之后才算真正存在于仓库中。因此整个流程的核心工作是对每一个注册面做适用 / 不适用的分类并更新所有适用的注册面而不是专注于目录复制。这套方法论在仓库中可找到直接佐证根目录 pnpm-workspace.yaml 声明了packages/*、packages/ai/*、packages/atom/*、packages/platform/*、packages/sql/*、packages/tools/*以及examples/*等 globtsconfig.packages.json 维护着 30 余条 project-referencevitest.config.ts 中为每个包显式注册了一个 test project。任何一个新包漏掉其中一环都可能出现本地能编译、仓库级校验却找不到它的割裂状态。七步工作流总览步骤动作完成条件Continue when…1审视同族最近包分类发布状态、运行时、测试环境、平台支持、barrel 与依赖形态每个拟创建的文件都有先例或明确的仓库需求作为理由2创建或移动源码、测试、TypeScript 与 manifest 文件依赖变更时按角色分类pnpm 能发现预期的包名manifest 不再引用不存在的文件3读取注册面清单逐项分类并更新所有适用的注册面每个注册面都完成分类旧的引用得到解释4仅发布包按发布审计流程核对开发面与打包面—5若包持有生成的 barrel运行 codegen 并检查生成段生成段与源码模块一致、无需手工修改6运行聚焦测试与脚本 适用的根级检查发布包需构建并 dry pack聚焦检查与根级检查通过打包面符合预期7应用根 changeset、生成文件、文档与 workflow 路由发现、注册、生成、验证、打包、changeset 路由全部验证或标记为不适用下文按这七个步骤逐一展开并给出仓库内的具体文件作为对照。步骤 1审视同族最近包让每个文件都有先例理由工作流的起点不是创建目录而是检查同一家族中最接近的包。Effect 仓库的包按家族组织得相当清晰AI 家族packages/ai/anthropic、packages/ai/openai、packages/ai/openai-compat、packages/ai/openrouterAtom 家族packages/atom/react、packages/atom/solid、packages/atom/vue平台家族packages/platform/browser、packages/platform/bun、packages/platform/deno、packages/platform/node、packages/platform/node-sharedSQL 家族packages/sql/pg、packages/sql/mysql2、packages/sql/sqlite-node、packages/sql/sqlite-wasm等工具家族packages/tools/*。审视时需要分类并记录六个维度发布状态是否对外发布、运行时Node / Bun / Deno / 浏览器、测试环境node / jsdom / happy-dom、平台支持哪些运行时被支持、barrel 形态是否有src/index.ts聚合导出、是否由 codegen 生成、依赖形态依赖的角色与版本策略。SKILL.md 的要求是Justify each proposed file by precedent or an explicit repository need——你提议创建的每一个文件要么能在同族包中找到先例要么能给出仓库层面的明确需求当所有文件都得到理由后才能进入下一步。这一原则在仓库中有实例可循例如 packages/atom/vue/package.json 与 packages/atom/react 共享相同的buildtsc -b babel annotate-pure-calls、check脚本和files形态新包照此对齐即可。步骤 2创建文件并给每个依赖一个角色创建或移动源码、测试、TypeScript 与 manifest 文件时关键约束是manifest 依赖一旦变化必须阅读 依赖角色说明把每一个依赖条目按角色分类。文档定义了五类角色角色适用场景dependencies发布后的运行时代码需要该包且应当获得一份属于自己的安装副本peerDependencies消费者提供兼容的共享包或公开契约需要与消费者自己的副本集成devDependencies仅仓库构建、测试、类型测试、基准或代码生成需要该包optionalDependencies运行时特性能够处理包缺失的情况且安装失败不得阻塞基础包可选 peer经peerDependenciesMeta消费者提供的集成是真正可选的其版本仍保留在peerDependencies中以 packages/atom/vue/package.json 为真实样例effect同时出现在devDependenciesworkspace:^供构建与测试和peerDependenciesworkspace:^供消费者集成中vue的 peer 范围写为3.5.39 4.0.0同时以^3.5.42作为 dev 依赖保证仓库测试所用版本。这正对应 dependencies.md 中的策略当本地构建或测试需要一个已安装的 peer 时把该 peer 以仓库已测试的版本加入devDependencies同时 peer 范围仍以受支持的消费者版本为准。其他要点还包括工作区版本工作区包默认使用workspace:^除非同族包确立了不同策略外部版本从当前拥有相同集成形态的消费者处推导外部依赖版本不要照抄相邻 manifest 中本包并未用到的条目安装与构建策略编辑完 manifest 后运行根pnpm install检查告警与 lockfile importer若某依赖有安装脚本或原生构建需按仓库当前策略登记到pnpm-workspace.yaml#allowBuilds。仓库现状中allowBuilds列出了core-js、cpu-features、dprint、esbuild、protobufjs、sharp、ssh2、tree-sitter系列与workerd等条目当前均显式设为false同时verifyDepsBeforeRun: error与enableGlobalVirtualStore: false两个仓库级约束也可在 pnpm-workspace.yaml 中直接核对完成条件每个依赖条目都有一个明确理由的角色workspace 与 peer 范围遵循仓库策略lockfile importer 与 manifest 一致安装/构建策略显式化。步骤 3逐面核对注册面清单——这是整个流程的重心SKILL.md 要求先阅读 注册面清单并把每个注册面分类为适用 / 不适用。包本地的构建成功并不能证明仓库级注册完成A package-local build does not prove repository registration。注册面共分四组下面结合仓库真实配置逐组展开。3.1 工作区与 TypeScript注册面检查点pnpm-workspace.yamlglob 覆盖包路径且按精确包名选择时 pnpm 能发现它pnpm-lock.yaml当前 importer、包名与依赖存在重命名/移动后旧 importer 消失tsconfig.packages.json需参与根 project-reference 图的包被引用遵循同族包策略可构建的私有工具不会自动纳入tsconfig.tests.json宽泛的测试 glob 覆盖该路径仅在测试需要工作区源码路由或会产生依赖环时才加源码别名保留有意的平台排除仓库实证pnpm-workspace.yaml 中packages/*与packages/ai/*、packages/atom/*、packages/platform/*、packages/sql/*、packages/tools/*的组合正是为了同时覆盖一层与两层的包布局tsconfig.packages.json 的references数组逐条列出packages/ai/anthropic、packages/sql/pg、packages/tools/doctest等路径——新包或移动后的包必须出现在这里根构建才能把它纳入编译图。而 tsconfig.tests.json 同时用./packages/*/test/**/*.ts与./packages/**/test/**/*.ts覆盖两种目录深度并用paths别名如effect/sql-sqlite-node: [./packages/sql/sqlite-node/src/index.ts]解决测试中的工作区引用其注释明确说明这些别名是为了在测试中加载内部模块、或加载本会造成循环依赖的其他工作区包。3.2 测试与文档注册面检查点vitest.config.ts有运行时测试的包应具有预期的 project、环境、setup 与包含规则tstyche.json类型测试发现覆盖包深度当前 glob 覆盖一层与两层包布局vitest.docs.tsdoctest 源码发现覆盖含可运行 JSDoc 示例的包当前 glob 覆盖一层与两层布局jsdocs.config.json公共源码被纳入 JSDoc 检查且按包家族的排除是有意的deno.jsonDeno 检查覆盖包家族或其排除是有意的仓库实证根 vitest.config.ts 用project(name, directory, include, config, exclude, include)辅助函数为每个包注册独立的 test project并按运行时条件启停——isNode/isBun/isDeno决定effect/platform-node、effect/platform-bun、effect/platform-deno等是否纳入effect/atom-react与effect/atom-solid使用jsdom环境effect/atom-vue与effect/platform-browser分别使用happy-dom集成测试由EFFECT_INTEGRATION_TESTS1、集群测试由EFFECT_CLUSTER_TESTS1门控effect/sql-mysql2在集成模式下还会关闭文件并行度以避免容器竞争。新增或移动一个包时需要在这里对齐 project 名称、目录、运行环境与 include 规则。tstyche.json 的testFileMatch同时包含packages/*/typetest/**/*.tst.*与packages/*/*/typetest/**/*.tst.*正是文档所说的一层与两层包布局覆盖。vitest.docs.ts 的includeSource同样写成packages/*/src/**/*.ts与packages/*/*/src/**/*.ts两条 glob。而 jsdocs.config.json 显式排除packages/tools/**、packages/**/src/internal/**、packages/**/src/index.ts、StandardSchema.ts与*Generated.ts——这些排除按家族保持有意状态新包若属于被排除家族则无需改动。deno.json 则把 workspace 限定为./packages/*与./packages/platform/*并在 exclude 中按家族排除packages/ai、packages/atom、packages/sql、packages/tools等目录新增 Deno 支持的包需要对照该清单。3.3 发布与发现注册面检查点.changeset/config.json已发布固定组fixed group成员使用当前包名私有工具不会仅因为能构建就被加入README.md公开目录条目包含当前名称、路径、描述与文档链接AI 文档复制工具与包files发布载荷包含所需的生成文档完整打包面审计见 publishing.mdSnapshot 发布 workflow快照发布能选中包路径现有 glob 可能已覆盖修改前先应用根 workflow 要求运行时特定 CI workflow运行时特定包参与适用的运行时任务修改前先应用根 workflow 要求仓库实证根 .changeset/config.json 中fixed列出整组同步发版的包effect、effect/ai-*、effect/atom-*、effect/platform-*、effect/sql-*、effect/vitest等而ignore中放的是scratchpad与scripts这类私有工具这正是固定组成员使用当前名称、私有工具不因能构建而加入的落点。像 scripts/package.json 这样private: true的目录仓库根也有ai-docs、scratchpad等私有工作区不应被塞进发布注册面。3.4 路径与消费者最后一组注册面要求审计根级工具 manifest 中显式的工作区包名用脚本搜索包家族、旧名称与旧路径定位路径敏感的 clean、codemod、circularity、copy 等行为对应 scripts 下的clean.mjs、codemod.mjs、circular.mjs、copy-ai-docs.mjs等工具。重命名或移动之后仓库中残留的每一处旧引用都必须给出解释。步骤 4发布包必须做打包面审计只有已发布published包才需要进入 发布审计流程。审计方式是与同族已发布包逐项对比 manifest重点包括exports 对齐开发期exports与publishConfig.exports按 key 对齐源码目标映射为构建后的目标被阻塞的内部路径与遗留路径继续阻塞。发布载荷核对当前 AI 文档复制工具与包files列表确认每个必需文件都在发布载荷中。入口对应每个公共源码入口恰好有一个发布对应物且不能暴露任何内部入口。真实样板依然可以看 packages/atom/vue/package.json开发期exports指向./src/index.ts与./src/*.ts并显式把./internal/*、./index、./*/index设为null阻塞publishConfig.exports则逐 key 映射为./dist/index.js与./dist/*.js同时保留同样的阻塞项。files数组包含src/**/*.ts、dist/**/*.js、dist/**/*.d.ts及ai-docs/**/*——后者正是发布载荷包含生成文档的证据。验证方式是在不发布的前提下构建并 dry pack运行当前根构建以触发发布载荷生成在临时目录生成 tarball检查其文件清单若涉及 manifest 转换还要检查打包后的package.json。该步骤的完成条件是包级与根级检查全部通过打包面恰好包含预期的文件、exports 与元数据。步骤 5codegen——生成段只检查、不手改当包拥有由 codegen 生成的 barrel聚合导出文件时需要运行 codegen随后只检查生成段而不是手工编辑。仓库中的典型生成来源包括packages/ai/*家族codegen.yml/codegen.yaml驱动对应 packages/ai/anthropic/codegen.yml 等、packages/effect中由 jsdocs 工具 生成的*Generated.tsjsdocs.config.json 明确排除*Generated.ts于手工检查之外以及 copy-ai-docs.mjs 这类将ai-docs复制进各包的发布载荷的工具。完成条件是生成段与源码模块一致、无需任何手工修改。步骤 6聚焦测试 根级检查 打包验证验证阶段要求运行聚焦的包测试与脚本外加适用的根级检查适用的包测试在对应包目录运行 vitest通过根 vitest.config.ts 中注册的 project注意环境与运行时条件如 Deno/Bun 下的排除项、EFFECT_INTEGRATION_TESTS/EFFECT_CLUSTER_TESTS开关公共 API 类型测试发布包通常需要通过 tstyche.json 覆盖的typetest/**/*.tst.*类型测试以及 tsconfig.tests.json 纳入的typetest目录JSDoc 示例 doctest包内可运行的 JSDoc 示例会被 vitest.docs.ts 的includeSource拾取并作为 doctest 运行发布包按发布审计流程构建并 dry pack确认打包面符合预期完成条件聚焦检查与根级检查全部通过打包面符合预期。步骤 7changeset、生成文件、文档与 workflow 路由收尾最后一步是把变更接入仓库的发布与协作机制changeset为发布包添加根级 changeset新增名称需要对照 .changeset/config.json 的fixed固定组确认成员身份私有工具如scripts、scratchpad按ignore策略处理生成文件将 codegen、AI 文档复制等生成的产物纳入最终提交生成段只检查、不手改文档若包属于公开目录更新根 README.md 中的目录条目名称、路径、描述、文档链接workflow 路由涉及快照发布或运行时特定 CI 的包需按根 workflow 的要求先应用根要求再编辑对应 workflow确认路径选择与运行时任务参与。完成标准SKILL.md 对整条流程给出明确的终点定义The task is complete when package discovery, registration, generated output, validation, packed output, and changeset routing are all verified or reported as not applicable.即六个环节——包发现pnpm workspace 与 lockfile、仓库注册TypeScript 引用、测试/文档配置、changeset 固定组、生成输出codegen barrel 与 AI 文档、验证聚焦与根级检查、打包输出dry pack 载荷、changeset 路由——要么全部得到验证要么被显式标记为不适用not applicable。不适用是一个合法的分类结果例如私有工具不需要发布审计纯浏览器包不需要 Deno 检查但每个不适用都必须是分类决策的产物而不是流程的遗漏。对照本文各节的完成条件逐项打勾即可在 Effect 仓库中以可复现、可审计的方式完成任何包级变更。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Effect 仓库包开发实操指南：把新增、重命名与移动工作区包当作“注册变更“来落地
Effect 仓库包开发实操指南把新增、重命名与移动工作区包当作注册变更来落地【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect导读本指南基于 Effect 仓库维护流程文档 .agents/skills/package-development/SKILL.md 及其配套的 依赖角色说明、注册面清单 与 发布审计流程系统讲解在 Effect 这个 pnpm monorepo 中正确新增一个工作区包、将私有包转为可发布包、以及重命名或移动包路径的标准流程。读完本文你将掌握一条可复用的七步工作流从审视同族包、起草依赖清单到逐项核对仓库注册面、验证打包产物最终以 changeset 收尾——每一步都能在当前仓库中找到真实的配置文件与实现证据作为对照。核心方法论包开发是注册变更不是目录拷贝SKILL.md 开篇给出了整个流程的锚点Treat package work as a registration change, not a directory copy.把包开发当作一次注册变更而不是一次目录拷贝。这句话的工程含义是在 Effect 这类多包仓库中新增一个包并不只是把src/、test/、package.json拷进packages/目录那么简单。一个包只有在被 pnpm workspace、TypeScript project references、vitest、tstyche、doctest、JSDoc、changeset、发布脚本等注册面registration surface全部认可之后才算真正存在于仓库中。因此整个流程的核心工作是对每一个注册面做适用 / 不适用的分类并更新所有适用的注册面而不是专注于目录复制。这套方法论在仓库中可找到直接佐证根目录 pnpm-workspace.yaml 声明了packages/*、packages/ai/*、packages/atom/*、packages/platform/*、packages/sql/*、packages/tools/*以及examples/*等 globtsconfig.packages.json 维护着 30 余条 project-referencevitest.config.ts 中为每个包显式注册了一个 test project。任何一个新包漏掉其中一环都可能出现本地能编译、仓库级校验却找不到它的割裂状态。七步工作流总览步骤动作完成条件Continue when…1审视同族最近包分类发布状态、运行时、测试环境、平台支持、barrel 与依赖形态每个拟创建的文件都有先例或明确的仓库需求作为理由2创建或移动源码、测试、TypeScript 与 manifest 文件依赖变更时按角色分类pnpm 能发现预期的包名manifest 不再引用不存在的文件3读取注册面清单逐项分类并更新所有适用的注册面每个注册面都完成分类旧的引用得到解释4仅发布包按发布审计流程核对开发面与打包面—5若包持有生成的 barrel运行 codegen 并检查生成段生成段与源码模块一致、无需手工修改6运行聚焦测试与脚本 适用的根级检查发布包需构建并 dry pack聚焦检查与根级检查通过打包面符合预期7应用根 changeset、生成文件、文档与 workflow 路由发现、注册、生成、验证、打包、changeset 路由全部验证或标记为不适用下文按这七个步骤逐一展开并给出仓库内的具体文件作为对照。步骤 1审视同族最近包让每个文件都有先例理由工作流的起点不是创建目录而是检查同一家族中最接近的包。Effect 仓库的包按家族组织得相当清晰AI 家族packages/ai/anthropic、packages/ai/openai、packages/ai/openai-compat、packages/ai/openrouterAtom 家族packages/atom/react、packages/atom/solid、packages/atom/vue平台家族packages/platform/browser、packages/platform/bun、packages/platform/deno、packages/platform/node、packages/platform/node-sharedSQL 家族packages/sql/pg、packages/sql/mysql2、packages/sql/sqlite-node、packages/sql/sqlite-wasm等工具家族packages/tools/*。审视时需要分类并记录六个维度发布状态是否对外发布、运行时Node / Bun / Deno / 浏览器、测试环境node / jsdom / happy-dom、平台支持哪些运行时被支持、barrel 形态是否有src/index.ts聚合导出、是否由 codegen 生成、依赖形态依赖的角色与版本策略。SKILL.md 的要求是Justify each proposed file by precedent or an explicit repository need——你提议创建的每一个文件要么能在同族包中找到先例要么能给出仓库层面的明确需求当所有文件都得到理由后才能进入下一步。这一原则在仓库中有实例可循例如 packages/atom/vue/package.json 与 packages/atom/react 共享相同的buildtsc -b babel annotate-pure-calls、check脚本和files形态新包照此对齐即可。步骤 2创建文件并给每个依赖一个角色创建或移动源码、测试、TypeScript 与 manifest 文件时关键约束是manifest 依赖一旦变化必须阅读 依赖角色说明把每一个依赖条目按角色分类。文档定义了五类角色角色适用场景dependencies发布后的运行时代码需要该包且应当获得一份属于自己的安装副本peerDependencies消费者提供兼容的共享包或公开契约需要与消费者自己的副本集成devDependencies仅仓库构建、测试、类型测试、基准或代码生成需要该包optionalDependencies运行时特性能够处理包缺失的情况且安装失败不得阻塞基础包可选 peer经peerDependenciesMeta消费者提供的集成是真正可选的其版本仍保留在peerDependencies中以 packages/atom/vue/package.json 为真实样例effect同时出现在devDependenciesworkspace:^供构建与测试和peerDependenciesworkspace:^供消费者集成中vue的 peer 范围写为3.5.39 4.0.0同时以^3.5.42作为 dev 依赖保证仓库测试所用版本。这正对应 dependencies.md 中的策略当本地构建或测试需要一个已安装的 peer 时把该 peer 以仓库已测试的版本加入devDependencies同时 peer 范围仍以受支持的消费者版本为准。其他要点还包括工作区版本工作区包默认使用workspace:^除非同族包确立了不同策略外部版本从当前拥有相同集成形态的消费者处推导外部依赖版本不要照抄相邻 manifest 中本包并未用到的条目安装与构建策略编辑完 manifest 后运行根pnpm install检查告警与 lockfile importer若某依赖有安装脚本或原生构建需按仓库当前策略登记到pnpm-workspace.yaml#allowBuilds。仓库现状中allowBuilds列出了core-js、cpu-features、dprint、esbuild、protobufjs、sharp、ssh2、tree-sitter系列与workerd等条目当前均显式设为false同时verifyDepsBeforeRun: error与enableGlobalVirtualStore: false两个仓库级约束也可在 pnpm-workspace.yaml 中直接核对完成条件每个依赖条目都有一个明确理由的角色workspace 与 peer 范围遵循仓库策略lockfile importer 与 manifest 一致安装/构建策略显式化。步骤 3逐面核对注册面清单——这是整个流程的重心SKILL.md 要求先阅读 注册面清单并把每个注册面分类为适用 / 不适用。包本地的构建成功并不能证明仓库级注册完成A package-local build does not prove repository registration。注册面共分四组下面结合仓库真实配置逐组展开。3.1 工作区与 TypeScript注册面检查点pnpm-workspace.yamlglob 覆盖包路径且按精确包名选择时 pnpm 能发现它pnpm-lock.yaml当前 importer、包名与依赖存在重命名/移动后旧 importer 消失tsconfig.packages.json需参与根 project-reference 图的包被引用遵循同族包策略可构建的私有工具不会自动纳入tsconfig.tests.json宽泛的测试 glob 覆盖该路径仅在测试需要工作区源码路由或会产生依赖环时才加源码别名保留有意的平台排除仓库实证pnpm-workspace.yaml 中packages/*与packages/ai/*、packages/atom/*、packages/platform/*、packages/sql/*、packages/tools/*的组合正是为了同时覆盖一层与两层的包布局tsconfig.packages.json 的references数组逐条列出packages/ai/anthropic、packages/sql/pg、packages/tools/doctest等路径——新包或移动后的包必须出现在这里根构建才能把它纳入编译图。而 tsconfig.tests.json 同时用./packages/*/test/**/*.ts与./packages/**/test/**/*.ts覆盖两种目录深度并用paths别名如effect/sql-sqlite-node: [./packages/sql/sqlite-node/src/index.ts]解决测试中的工作区引用其注释明确说明这些别名是为了在测试中加载内部模块、或加载本会造成循环依赖的其他工作区包。3.2 测试与文档注册面检查点vitest.config.ts有运行时测试的包应具有预期的 project、环境、setup 与包含规则tstyche.json类型测试发现覆盖包深度当前 glob 覆盖一层与两层包布局vitest.docs.tsdoctest 源码发现覆盖含可运行 JSDoc 示例的包当前 glob 覆盖一层与两层布局jsdocs.config.json公共源码被纳入 JSDoc 检查且按包家族的排除是有意的deno.jsonDeno 检查覆盖包家族或其排除是有意的仓库实证根 vitest.config.ts 用project(name, directory, include, config, exclude, include)辅助函数为每个包注册独立的 test project并按运行时条件启停——isNode/isBun/isDeno决定effect/platform-node、effect/platform-bun、effect/platform-deno等是否纳入effect/atom-react与effect/atom-solid使用jsdom环境effect/atom-vue与effect/platform-browser分别使用happy-dom集成测试由EFFECT_INTEGRATION_TESTS1、集群测试由EFFECT_CLUSTER_TESTS1门控effect/sql-mysql2在集成模式下还会关闭文件并行度以避免容器竞争。新增或移动一个包时需要在这里对齐 project 名称、目录、运行环境与 include 规则。tstyche.json 的testFileMatch同时包含packages/*/typetest/**/*.tst.*与packages/*/*/typetest/**/*.tst.*正是文档所说的一层与两层包布局覆盖。vitest.docs.ts 的includeSource同样写成packages/*/src/**/*.ts与packages/*/*/src/**/*.ts两条 glob。而 jsdocs.config.json 显式排除packages/tools/**、packages/**/src/internal/**、packages/**/src/index.ts、StandardSchema.ts与*Generated.ts——这些排除按家族保持有意状态新包若属于被排除家族则无需改动。deno.json 则把 workspace 限定为./packages/*与./packages/platform/*并在 exclude 中按家族排除packages/ai、packages/atom、packages/sql、packages/tools等目录新增 Deno 支持的包需要对照该清单。3.3 发布与发现注册面检查点.changeset/config.json已发布固定组fixed group成员使用当前包名私有工具不会仅因为能构建就被加入README.md公开目录条目包含当前名称、路径、描述与文档链接AI 文档复制工具与包files发布载荷包含所需的生成文档完整打包面审计见 publishing.mdSnapshot 发布 workflow快照发布能选中包路径现有 glob 可能已覆盖修改前先应用根 workflow 要求运行时特定 CI workflow运行时特定包参与适用的运行时任务修改前先应用根 workflow 要求仓库实证根 .changeset/config.json 中fixed列出整组同步发版的包effect、effect/ai-*、effect/atom-*、effect/platform-*、effect/sql-*、effect/vitest等而ignore中放的是scratchpad与scripts这类私有工具这正是固定组成员使用当前名称、私有工具不因能构建而加入的落点。像 scripts/package.json 这样private: true的目录仓库根也有ai-docs、scratchpad等私有工作区不应被塞进发布注册面。3.4 路径与消费者最后一组注册面要求审计根级工具 manifest 中显式的工作区包名用脚本搜索包家族、旧名称与旧路径定位路径敏感的 clean、codemod、circularity、copy 等行为对应 scripts 下的clean.mjs、codemod.mjs、circular.mjs、copy-ai-docs.mjs等工具。重命名或移动之后仓库中残留的每一处旧引用都必须给出解释。步骤 4发布包必须做打包面审计只有已发布published包才需要进入 发布审计流程。审计方式是与同族已发布包逐项对比 manifest重点包括exports 对齐开发期exports与publishConfig.exports按 key 对齐源码目标映射为构建后的目标被阻塞的内部路径与遗留路径继续阻塞。发布载荷核对当前 AI 文档复制工具与包files列表确认每个必需文件都在发布载荷中。入口对应每个公共源码入口恰好有一个发布对应物且不能暴露任何内部入口。真实样板依然可以看 packages/atom/vue/package.json开发期exports指向./src/index.ts与./src/*.ts并显式把./internal/*、./index、./*/index设为null阻塞publishConfig.exports则逐 key 映射为./dist/index.js与./dist/*.js同时保留同样的阻塞项。files数组包含src/**/*.ts、dist/**/*.js、dist/**/*.d.ts及ai-docs/**/*——后者正是发布载荷包含生成文档的证据。验证方式是在不发布的前提下构建并 dry pack运行当前根构建以触发发布载荷生成在临时目录生成 tarball检查其文件清单若涉及 manifest 转换还要检查打包后的package.json。该步骤的完成条件是包级与根级检查全部通过打包面恰好包含预期的文件、exports 与元数据。步骤 5codegen——生成段只检查、不手改当包拥有由 codegen 生成的 barrel聚合导出文件时需要运行 codegen随后只检查生成段而不是手工编辑。仓库中的典型生成来源包括packages/ai/*家族codegen.yml/codegen.yaml驱动对应 packages/ai/anthropic/codegen.yml 等、packages/effect中由 jsdocs 工具 生成的*Generated.tsjsdocs.config.json 明确排除*Generated.ts于手工检查之外以及 copy-ai-docs.mjs 这类将ai-docs复制进各包的发布载荷的工具。完成条件是生成段与源码模块一致、无需任何手工修改。步骤 6聚焦测试 根级检查 打包验证验证阶段要求运行聚焦的包测试与脚本外加适用的根级检查适用的包测试在对应包目录运行 vitest通过根 vitest.config.ts 中注册的 project注意环境与运行时条件如 Deno/Bun 下的排除项、EFFECT_INTEGRATION_TESTS/EFFECT_CLUSTER_TESTS开关公共 API 类型测试发布包通常需要通过 tstyche.json 覆盖的typetest/**/*.tst.*类型测试以及 tsconfig.tests.json 纳入的typetest目录JSDoc 示例 doctest包内可运行的 JSDoc 示例会被 vitest.docs.ts 的includeSource拾取并作为 doctest 运行发布包按发布审计流程构建并 dry pack确认打包面符合预期完成条件聚焦检查与根级检查全部通过打包面符合预期。步骤 7changeset、生成文件、文档与 workflow 路由收尾最后一步是把变更接入仓库的发布与协作机制changeset为发布包添加根级 changeset新增名称需要对照 .changeset/config.json 的fixed固定组确认成员身份私有工具如scripts、scratchpad按ignore策略处理生成文件将 codegen、AI 文档复制等生成的产物纳入最终提交生成段只检查、不手改文档若包属于公开目录更新根 README.md 中的目录条目名称、路径、描述、文档链接workflow 路由涉及快照发布或运行时特定 CI 的包需按根 workflow 的要求先应用根要求再编辑对应 workflow确认路径选择与运行时任务参与。完成标准SKILL.md 对整条流程给出明确的终点定义The task is complete when package discovery, registration, generated output, validation, packed output, and changeset routing are all verified or reported as not applicable.即六个环节——包发现pnpm workspace 与 lockfile、仓库注册TypeScript 引用、测试/文档配置、changeset 固定组、生成输出codegen barrel 与 AI 文档、验证聚焦与根级检查、打包输出dry pack 载荷、changeset 路由——要么全部得到验证要么被显式标记为不适用not applicable。不适用是一个合法的分类结果例如私有工具不需要发布审计纯浏览器包不需要 Deno 检查但每个不适用都必须是分类决策的产物而不是流程的遗漏。对照本文各节的完成条件逐项打勾即可在 Effect 仓库中以可复现、可审计的方式完成任何包级变更。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
