Astryx 集成自动链接Autolink机制解析安装即发现无需 astryx.config 声明【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx本篇文章围绕 Astryx CLIastryxdesign/cli的一项核心能力展开当一个 npm 包被项目声明为直接依赖、且随包携带astryx.integration.*清单时CLI 会自动加载它为集成无需在astryx.config中写任何一行声明。读完本文你将理解该机制的完整判定规则、底层源码调用链、与显式配置的优先级关系以及如何借助astryx doctor的implicit-integrations检查回答CLI 为什么能看到这个集成和这个依赖能否删除两个问题。背景集成为什么曾经装了就消失在 Autolink 机制之前一个集成要真正对项目生效需要同时满足两个条件该包已被安装到项目的node_modules包名被显式写入astryx.config.{ts,mjs,js}的integrations数组。实际项目中第二半经常缺失。典型的失败场景是脚手架scaffold只负责添加依赖、却不生成任何配置于是这个随包提供组件components、模板templates、文档docs和升级 codemod 的包在 CLI 眼里完全不存在——所有贡献都被报告为缺失而缺失与根本没安装在输出上无法区分。因为没有任何东西报错也就没人去排查集成便一直处于被安装却从未被使用的状态。Autolink 正是从永远为真的那一侧补上这个缺口一个项目声明为依赖、且随包携带根级astryx.integration.*清单的包就是一个集成无论配置里有没有它。该变更的说明与版本记录位于 .changeset/autolink-installed-integrations.md实现代码位于 packages/cli/foundation/integrations/autolink.mjs。三条核心判定规则Autolink 的行为由三条规则严格约束任何一条都是有意为之的边界设计。规则一只探测声明的依赖绝不遍历 node_modules被探测的字段仅有三个定义在 autolink.mjs 的DEPENDENCY_FIELDSdependenciesdevDependenciesoptionalDependenciespeerDependencies被刻意排除peer 是要求消费者去满足的依赖并非本项目安装行为带来的东西因此恰好存在一个 peer不等于本项目声明了它属于这里。CLI 只读取项目自身package.json中的依赖键key逐个解析从不遍历node_modules查找清单。这意味着一个传递依赖依赖的依赖即使携带 manifest也不会向本项目贡献任何东西——它没有被本项目声明自然无权参与。规则二只读键不读值acme/legacy-ui: npm:acme/ui0.1.22是真实存在的安装形态workspace:*、file:../lib、link:、catalog:同样如此。这些值没有一个是 semver 范围也完全不需要被解析——因为依赖键本身就是node_modules下的目录名这才是解析唯一需要的信息。测试 autolink.test.mjs 专门验证了这五种非 semver 值形态都能正常加载。规则三身份来自包自身的 name集成身份identity始终来自被解析包的package.json中的name而不是它在依赖里的键名。由此推出两个行为别名依赖如实报告acme/legacy-ui: npm:acme/ui0.1.22解析后报告的集成是acme/ui而不是键名acme/legacy-ui两个键指向一个包只加载一次无论是一个 npm 别名紧挨着它别名的原包还是重命名过渡期的两种拼写通过同一个 pnpm store 条目解析到同一真实路径都会按真实路径fs.realpathSync去重只加载一次。源码实现走读Autolink 处于三层结构的中间位置Project.load是调用方integrations.mjs是清单加载器autolink.mjs本身不产生任何发现逻辑。下面沿调用链自底向上梳理。1. 读取声明的依赖readDeclaredDependenciesautolink.mjs 按dependencies → devDependencies → optionalDependencies的字段顺序、字段内声明顺序读取键并用Set去重——一个名字在多个字段出现时保留首次出现的字段。键名必须通过isBarePackageName守卫L69-L77拒绝绝对路径、/开头、以及含./..路径段的名字防止后续动态 import 被指向任意模块。package.json缺失或损坏时返回空数组视为无声明。2. 解析安装目录resolveInstalledPackageDirautolink.mjs 复刻 Node 解析器的行为从项目目录向上逐层查找最近的node_modules/name。向上查找是必须的——yarn 与 npm workspace 通常把 workspace 成员的依赖提升到仓库根目录导致应用自己的node_modules里没有它确实声明的包。判存依据是目标目录下存在package.json而非目录本身存在从而避免把残留的空目录误认为已安装。3. 筛选候选findAutolinkCandidatesautolink.mjs 对每个声明的依赖做三重过滤恰好一个根级 manifest零个是绝大多数普通依赖的常态多于一个属于打包错误。这里的关键在于对配置外的自动链接候选多 manifest 直接跳过绝不允许一个项目没点名要的包拖垮整个Project.load排除已加载通过exclude参数来自 config 已加载的__packageDir且经realpath比较pnpm 场景下符号链接到同一真实路径的也会被排除去重两个依赖键解析到同一真实路径时只保留一个候选。4. 隔离加载autolinkIntegrationsautolink.mjs 逐个隔离加载候选从真正持有该包的hostDir解析hoisting 后包的解析方式与 Node 找到它的方式一致加载失败manifest 抛出异常或 schema 校验失败直接continue跳过——静默丢弃不产生任何 issue。理由在注释中写得很清楚被配置的集成是项目点名要的其失败是项目自己的问题、可以处理而自动链接的集成失败属于依赖自身的打包缺陷消费方既修不了也静默不掉不应该当成消费方项目的问题来报告。astryx doctor integration validate package是按需检查这种打包问题的入口已加载成功的集成打上__autolinked: true与__dependencyField声明它的 package.json 字段两个内部标记。5. 编排入口Project.loadpackages/cli/foundation/config/project.mjs 的加载顺序是解析 config → loadIntegrations(显式配置) → autolinkIntegrations(自动链接) → loadLocalIntegration(本地包自解析)关键设计在 L283-L297Autolink无论是否存在 config 都会运行——它要覆盖的恰恰是那些没有任何 astryx.config的项目scaffold 只加依赖不写配置。自动链接结果追加在显式配置之后保证显式条目在所有发现顺序中都保持自己的位置与优先级。最后loadLocalIntegration处理唯一无法安装自己的包当作者正站在一个携带 manifest 的包目录内工作时直接解析其工作目录字节让作者在发布前就能预览自己的贡献。6. 清单协议集成清单是一份与package.json平级的根文件合法的基名按加载优先级定义在 integrations.mjsastryx.integration.ts / astryx.integration.mjs / astryx.integration.js加载器只允许恰好一个缺失或重复都是硬错误。清单的 default export 声明各类贡献根目录与问题追踪地址典型形态来源cli-integrations.doc.mjs// astryx.integration.ts export default { components: ./components, templates: ./templates, themes: ./themes, codemods: ./codemods, docs: ./docs, issuesUrl: https://github.com/acme/widgets/issues, };身份name、version来自包自身的package.json而非 manifest。每个贡献根在解析时都会经过assertWithin路径安全校验越界则被静默置空。加载完成后LoadedIntegration携带一组__前缀的内部簿记字段__spec、__packageDir、__manifestFile、__autolinked、__dependencyField、__loadError等见 integrations.mjs。优先级与错误处理边界场景行为显式astryx.config条目 同样安装了该包config 条目优先自动链接跳过该包条目保持原位置与顺序自动链接的 manifest 加载失败静默丢弃该包及其全部贡献不产生 project issue不拖垮加载显式配置的集成加载失败属于项目自己的问题通过Project.issues()上报并跳过其贡献候选包有多个 manifest视为打包错误自动链接阶段直接跳过防止无关包拖垮项目依赖值是非 semver 形态npm:、workspace:、file:、link:、catalog:只按键解析正常加载两个依赖键指向同一真实包只加载一次加载后的集成按skip warn策略参与各类发现components()、templates()、themes()、docs()、codemods()各自逐个隔离处理每个集成任何一个集成的故障只跳过自己绝不向发现循环外抛异常并累积到issues()中见 project.mjs。astryx doctor新增的 implicit-integrations 检查Autolink 引入后带来两个新的实际问题而 doctor.mjs 中的checkImplicitIntegrations检查id 为implicit-integrations正是对这两个问题的统一回答CLI 为什么能看到这个——作者在项目里 grep 不到包名不应被要求去读 CLI 源码才能理解这个依赖能删吗——unused-dependency 扫描只看源码 import而恰好自动链接的集成在源码里没有任何 importmanifest 就是它与项目的全部连接因此必须在 doctor 输出中把这个依赖标记为承重。输出内容对每个自动链接的集成该行会输出包名与版本如acme/widgets1.0.0当 npm 别名使键名与包名不同时额外标注(declared as acme/legacy-ui)声明它的 package.json 字段dependencies/devDependencies/optionalDependencies它贡献的内容从components、templates、themes、docs、codemods中筛出实际存在的根。示例输出形态info: 2 integrations loaded from installed dependencies with no astryx.config entry: acme/widgets1.0.0 from dependencies, contributing components, templates, themes; acme/ui0.1.22 (declared as acme/legacy-ui) from devDependencies, contributing docs.始终是 infoCI gate 不受影响doctor 的状态语义为pass/warn/fail/info其中只有fail驱动退出码 1作为 CI gate。implicit-integrations永远返回info——一个正确引入了集成的项目没有任何需要告警的事该检查的意义是陈述什么被加载了而不是推动任何人去写配置。fix文本明确写着无需修复保持依赖安装即可同时提醒——若 unused-dependency 检查只看源码 import会把这些依赖误报为未使用此时可在astryx.config.*的integrations中显式列出以把链接关系写明。该行为由 doctor.test.mjs 验证无论输入为空、全配置、还是混合状态状态恒为info且该检查稳定出现在 doctor 报告中。在整套诊断中的位置checkImplicitIntegrations是 doctor 引擎九个同步检查之一SYNC_CHECKS完整清单包括检查 id内容node-versionNode 版本是否达到 CLI 最低要求core-installedastryxdesign/core是否已安装并可解析version-alignmentcore 与 cli 的 major/minor 是否对齐themes是否安装了astryxdesign/theme-*且已接线configastryx.config.mjs能否加载、形状是否合法implicit-integrations自动链接的集成本文主题agent-docsAGENTS.md / CLAUDE.md / .cursorrules 中是否存在 Astryx 区块标记peer-depscore 的 peer 依赖是否满足package-manager检测包管理器及 lockfile 冲突引擎本身是纯读操作不安装、不写入、不修改任何东西因此既适合作为 CI gate也适合 AI Agent 以--json形式调用见 doctor.mjs 的程序化doctor()API。测试证据autolink 单元与集成测试autolink.test.mjs 用仓库内临时目录构造真实项目形态脚手架只加依赖不写配置、npm 别名、重命名双拼写、hoisted 安装覆盖的核心断言包括只读三个依赖字段、不读peerDependencies重名保留首字段L108-L143拒绝非裸包名键../evil、/abs、./relpackage.json损坏时返回空L131-L142hoisting 场景向上解析到 workspace 根、且就近优先L145-L173只探测声明依赖、忽略携带 manifest 的传递依赖、跳过无 manifest 依赖、跳过多 manifest 包L175-L219pnpm 符号链接下两个键折叠为一个真实路径、排除已从 config 加载的包L221-L246五种非 semver 依赖值npm: 别名、link:、file:、workspace:、catalog:全部按键加载成功且别名包以自身name为身份L265-L305manifest 抛异常 / 校验失败的包被静默丢弃且Project.issues()为空L341-L367端到端验证无任何 config 的项目仅凭依赖声明即可从自动链接的集成中发现组件MetaOncall显式配置的集成排在前、自动链接的排在后hoisted workspace 根同样可解析无集成项目完全不受影响L370-L430。doctor 检查测试doctor.test.mjs 覆盖checkImplicitIntegrations的分支项目不可读时跳过无安装时报告 none全部已配置时报告 none正常时输出包名版本、来源字段、贡献列表别名时输出声明键并验证fix文本中包含 unused-dependency 检查与astryx.config指引。作者与消费者视角集成作者不要手工编写 manifest而是让 CLI 生成。每条integration add命令都是非交互的、拒绝覆盖已有文件、支持--dry-run且只在真正写入合法贡献后才在 manifest 中声明对应根astryx integration add component AcmeCarousel astryx integration add doc deploying astryx integration add template dashboard --type page astryx integration add codemod rename-prop --to 1.2.0 astryx integration add agent-doc Use AcmeCarousel for rotating content. astryx integration add theme ocean发布前运行包门禁astryx integration pack --check它执行真实包生命周期、创建 npm tarball、核对每个必需贡献文件是否在 pack 清单内、解包到临时消费项目并比对本地与打包后的贡献清单详见 cli-integrations.doc.mjs。作者在包目录内运行astryx component --list、astryx docs、astryx template --list、astryx theme list即可看到本地贡献包自解析无需发布或搭建临时应用。消费者安装即生效——包必须是直接依赖npm install astryxdesign/core acme/astryx-widgets astryx component --list --package acme/astryx-widgets astryx docs brand-theme无需任何astryx.config条目。仅当应用需要控制集成顺序或显式化链接时才在配置中点名// astryx.config.ts export default { integrations: [acme/astryx-widgets], };此时该包仍保持显式条目原有的优先级与位置自动链接只服务于 config 未点名的包。若集成相关命令找不到目标astryx doctor integration validate package是可用的只读诊断面。小结Autolink 把安装即生效带入了 Astryx 的集成体系它以项目自身声明的依赖键为唯一事实来源用恰好一个根清单 包自身 name 身份界定候选用隔离加载 静默丢弃保证一个无关包或坏包永远无法拖垮项目加载用显式配置优先保住既有的顺序语义并用astryx doctor的implicit-integrations检查让CLI 看到了什么、为什么变成一行可读的输出。核心实现、测试与文档分别位于 packages/cli/foundation/integrations/autolink.mjs、packages/cli/foundation/integrations/autolink.test.mjs、packages/cli/api/doctor/doctor.mjs 与 packages/cli/assets/docs/cli-integrations.doc.mjs供继续深入阅读。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考