xy-toolchain

XY Toolchain

权威来源。 此技能仅在 ariestools/ariestools-skills 中维护。XYOracleNetwork/xyo-skills 下的副本是重定向存根——请在此处编辑，切勿在那些副本中编辑。如果仓库还包含 xylabs-* 技能、.claude/rules/xylabs-*.md，或 .claude/commands/xy-*.md 和 xylabs-*.md，它们都是已移除的 xy claude 命令生成的过时文件；此技能取代了它们。从 10.1.2 起，xy skills lint 会报告这些文件，--fix 会移除其中的大多数（旧版 Agent 文件）。

工具链版本。 此技能已通过 @ariestools/toolchain 10.1.5 验证；未标注“（自 X 起）”的内容均从 9.0.0 起提供。使用 pnpm list @ariestools/toolchain --depth 0 查找已安装的版本（只有从 10.0.6 起，pnpm xy --version 才可靠）。如果已安装版本中没有某个顶层命令，就会显示 Command not found。从 10.1.2 起，该命令会以 1 退出；在 10.1.1 及更早版本中，缺失的都是较新的命令，即使使用 --strict，退出码也为 0。缺失的子命令可能会被静默忽略（例如，xy node <typo> 只会显示横幅并以 0 退出），也可能被当作软件包目标读取，因此请检查输出和版本说明，而不要只看退出码。版本说明汇总了各项命令的版本要求。

技能标识。 在给出计划、确认或完成摘要时，请注明为其提供依据的技能，格式为 xy-toolchain v<version>，并以相同格式列出此技能包中的其他所有已启用技能。版本请读取此文件中的 metadata.version，切勿从示例或 verified-toolchain 中读取。

请使用当前启用的 @ariestools/toolchain 软件包。新工作中不要安装已弃用的 @xylabs/* 兼容名称。

通道。 xy 遵循稳定的语义化版本。xyex（自 9.2.0 起）是实验性超集，其命令、标志和配置可能随次版本发布而变化。优先使用 xy；对于 pnpm xy --stability 标记为实验性的命令（例如 work、dead 和 plan），请使用 pnpm xyex <cmd>（9.2.0 之前，请参阅通道）。

选择命令前，请检查仓库的 package.json、锁文件、xy.config.ts、ESLint 配置、TypeScript 配置和测试配置。优先使用仓库中已有的脚本；如果仓库没有更精简的封装，则直接使用 xy CLI。

此技能以 xy-development 为基础，其中介绍了语言和工作流原则。请仅加载任务所需的参考资料：

参考资料

项目配置文件

在判定软件包的角色（库、库/CLI、CLI、服务、应用、工作区根目录、工具）、可见性、运行时和框架；选择通用、Node、浏览器或 React 指南；覆盖误判的 deplint 角色（例如，将单软件包服务检测为 workspace-root）；确定 monorepo 与单软件包设置有何不同；或判断由框架工具还是 xy compile 负责生产构建输出时，请先阅读此文档。

工具链和项目设置

在使用固定的 TypeScript 和 ESLint 版本范围安装工具链、设置 pnpm 和 pnpm-workspace.yaml、在 xy 和 xyex 之间选择、配置根脚本及其向 xy 的移交、区分 xy 命令和 package-* 钩子、使用 xy repo init 搭建脚手架或满足新项目基线要求、从 @xylabs/* 迁移、将 9.x 升级到 10.x、移除旧版 xy claude Agent 文件、检查某个命令由哪个工具链版本引入，或排查项目设置问题时，请阅读此文档。

编译和包输出

编辑 xy.config.ts 时（包括哪些设置会从根目录级联），选择 neutral/node/browser 目标，选择 library/bundle/transpile/monolith/vendor 模式，配置类型验证或实验性原生编译器，使 monolith 的 #imports 与其导出保持一致，或排查生成的文件和导出布局时，请阅读本文。

命令和策略目录

在选择 xy 和 xyex 命令、运行生命周期或 CI 门禁（build、check、fix、test）、修复 deplint（包角色、not-public、放置/存在性、pick）、api-exposure、publint、license、secure 或仓库策略问题（包括 nodeTrack）时，请阅读本文；使用 xy agent 检查 AGENTS.md 和文档（自 10.1.1 起；xy check 会运行其 lint，自 10.1.2 起仅在存在 AGENTS.md 或声明了 commands.agentLint 时运行；自 10.1.5 起支持实验性的 --fix-interactive）；管理 xy skills（层级、package.json xy.skills、各项 skill 的存在性、pick）；使用 xyex work 跟踪工作（GitHub Issues 双写与同步、多文件夹 --workspace 范围）；配置 clean；使用 deploy 和 publish 发布（--tag、--defer）；维护依赖（install、reinstall、up、带有 commands.updo.ignoreDeps 的 updo）；使用其他实验性 xyex 命令（dead、plan、npm-org，等等）；或设置规则级别并使用 --rules、--json、--strict 和自动化行为时，也请阅读本文。

计划工具

为 xy-product-plan 流程搭建产品仓库（论文、docs/ROADMAP.md、各版本 PRD），或决定是否以及如何配合使用实验性的 xyex plan lint 或 .xy/plan.json 时，请阅读本文。本文介绍 xy repo init 和 xy agent init 会创建什么、xy agent lint 会检查论文、路线图和 PRD 的哪些内容（以及没有任何工具检查版本固定项）、与产品前缀、Red 和 Light 论文冲突的 plan lint 规则以及如何关闭这些规则、清单中的论文槽位和路线图阶段，以及如何将 xyex work 项目关联到 PRD。

ESLint 配置

创建或修复 ESLint 扁平配置（使用 xy lint init 或手动操作）、选择规则层级、修复默认层级下遇到的规则问题、启用或限定类型感知 lint、遵循 .gitignore、覆盖导入限制而不移除共享禁用项、诊断 lint 缓存或性能问题，或使用 lint lint 和 lint config 时，请阅读本文。

TypeScript 配置

选择 @ariestools/tsconfig、-dom 或 -react 并固定 typescript 范围（绝不要使用 7），解读 noEmit、erasableSyntaxOnly 等基础选项以及装饰器所需的 tslib，配置 Node 类型和按目标划分的类型检查流程，使用 @ariestools/lib-neutral 全局环境声明，或将类型验证与工具链输出分离时，请阅读本文。

使用 Vitest 进行测试

配置 Vitest（@ariestools/vitest-config 预设及其随版本变化的默认 include，或手动编写的配置）、选择 spec 位置和 node/browser 路由、为浏览器测试安装 Chromium、运行工作区或路径并了解 xy test 如何转交给根脚本、放置完整应用的 Playwright e2e 测试、清除测试缓存，或区分测试失败与构建失败时，请阅读本文。

相关技能

这些是导航链接，不是依赖项；每项技能都需单独安装。

• xy-development — 基础技能：TypeScript、Git、测试原则和完成定义。安装：npx skills add ariestools/ariestools-skills --skill xy-development。
• ariestools-sdk — sdk-js 中的 @ariestools/sdk 实用工具和专业软件包；它基于此技能构建。安装：npx skills add ariestools/ariestools-skills --skill ariestools-sdk。
• ariestools-sdk-react — 基于 @ariestools/sdk-react* 的 React UI：软件包、对等依赖、导入规则和项目惯例；它基于此技能及其 React 配置构建。安装：npx skills add ariestools/ariestools-skills --skill ariestools-sdk-react；或者，从 10.1.4 起，使用 pnpm xy skills pick --skill ariestools-sdk-react，该命令也会将其记录为必需技能；在使用 @ariestools/sdk-react* 软件包的地方，xy skills lint 会要求安装该技能（xy skills）。
• ariestools-actor — 由 cli-kit 或 browser-kit 托管的 actor-kit actors、providers 和 actor 引擎；它基于此技能构建。安装：npx skills add ariestools/ariestools-skills --skill ariestools-actor；或者，从 10.1.4 起，使用 pnpm xy skills pick --skill ariestools-actor，该命令也会将其记录为必需技能；在使用 actor-kit、cli-kit 或 browser-kit 软件包的地方，xy skills lint 会要求安装该技能（xy skills）。
• xy-agent — AGENTS.md、docs/ 和 papers/ 的约定，由稳定版 xy agent lint 检查（自 10.1.1 起；xy check 会运行它；自 10.1.2 起，仅当存在 AGENTS.md 或声明了 commands.agentLint 时运行），并提供 xy agent init|audit|index|archive 辅助命令（xy agent）。安装：npx skills add ariestools/ariestools-skills --skill xy-agent；或者使用 pnpm xy skills pick --skill xy-agent（自 10.1.2 起），该命令也会将其记录为必需技能。
• xy-product-plan — 与工具无关的产品规划流程（White、Yellow、Green、Red 和 Light papers、路线图的 MVP 线、各版本 PRD），由 Plan 工具提供支持。安装：npx skills add ariestools/ariestools-skills --skill xy-product-plan。此技能不在 xy skills 目录中，因此 xy skills pick 会拒绝它。
• 领域脚手架（例如单独的 xyo-skills 软件包中的 XL1 应用）仍应依赖此处所述的活跃 @ariestools/* 工具链软件包。