tsdown Skills 解析：AI 编码代理如何用技能包掌握 tsdown，以及在 AIRI 单仓中的落地实践

本篇技术文章以 .agents/skills/tsdown/README.md 为核心，讲清楚 AIRI 仓库中 tsdown 技能包（Agent Skill）的定位、安装方式与内容构成，并结合仓库内 29 个 tsdown.config.ts 实际配置文件，展示该技能所覆盖的 tsdown 知识在真实 monorepo 构建体系中的对应关系。读完本文，你将理解"技能包"这种把 bundler 领域知识注入 AI 编码代理的机制，以及 tsdown 的关键配置模式如何在 AIRI 的 packages/、services/、plugins/ 中被实际使用。

1. tsdown Skills 是什么

.agents/skills/tsdown/README.md 的定义是：一套帮助 AI 编码代理理解并使用 tsdown（基于 Rolldown 的库打包器）的 Agent skills。技能包目录结构如下：

文件/目录	作用
SKILL.md	技能主文件，含 frontmatter 元数据（name、description）与完整知识大纲
references/	38 个参考文档，覆盖指南、配置选项、高级主题、框架配方与 CLI 参考
SYNC.md	同步元信息：来源、Git SHA、同步日期
README.md	本技能的说明文档（即本文核心文档）
LICENSE.md	许可证（MIT）

从仓库根目录的 skills-lock.json 可以看到，AIRI 对仓库内的每个技能都做了哈希锁定管理。tsdown 技能的锁定条目记录其来源（sourceType: github、skillPath: skills/tsdown/SKILL.md）与 computedHash，用于校验技能内容未被意外篡改。这是一种可审计的技能依赖管理机制——技能本身像第三方依赖一样被"锁定版本"。

2. 安装方式

README 给出了两条安装命令（面向使用 skills CLI 的代理环境，例如 Claude Code）：

# 安装全部 tsdown 技能（含迁移技能）
npx skills add rolldown/tsdown

# 只安装 tsdown 技能
npx skills add rolldown/tsdown --skill tsdown

值得注意的是 AIRI 仓库的本地做法与官方安装路径的差异：仓库将技能同步（vendor）进了 .agents/skills/tsdown/ 目录，SYNC.md 记录了同步元信息——来源路径 vendor/tsdown/skills/tsdown、Git SHA f635a43b3c8b18569b47f3789c801f44a45c668a、同步日期 2026-06-22。也就是说，AIRI 团队选择了"同步进仓库 + 哈希锁定"而不是每次运行时 npx 拉取，这样任何协作者（包括 AI 代理）在离线环境下也能拿到完全一致的技能内容，并且 skills-lock.json 中的 computedHash 可作为内容完整性的校验依据。

3. 技能内容构成（What's Included）

README 列出了技能提供的 9 类知识，它们与 SKILL.md 中的表格一一对应，并映射到 references/ 下的具体文档：

• Core Concepts——tsdown 是什么、为什么用它、关键特性。对应 references/guide-introduction.md。
• Configuration——配置文件格式、选项、多配置、workspace 支持。对应 references/option-config-file.md。
• Build Options——入口点、输出格式、类型声明、target。对应 references/ 下 20 个 option-*.md 文件。
• Dependency Handling——external/inline 依赖、自动外部化。对应 references/option-dependencies.md。
• Output Enhancement——shims、CJS defaults、package exports。对应 references/option-shims.md、references/option-package-exports.md。
• Framework Support——React、Vue、Solid、Svelte 集成。对应 recipe-react.md、recipe-vue.md 等配方文档。
• Advanced Features——插件、hooks、编程式 API、Rolldown 选项透传。对应 references/advanced-plugins.md、references/advanced-hooks.md、references/advanced-programmatic.md。
• CLI Commands——完整 CLI 选项。对应 references/reference-cli.md。
• Migration——从 tsup 迁移到 tsdown。对应 references/guide-migrate-from-tsup.md。

references/README.md 进一步说明了这套参考文档的命名规范，这解释了为什么 references/ 目录下的 38 个文件呈现高度规律的前缀结构：

前缀	类别	示例
guide-*	入门指南与教程	guide-getting-started.md、guide-migrate-from-tsup.md
option-*	单个配置选项详解（20 个）	option-dts.md、option-target.md、option-css.md
advanced-*	高级主题（7 个）	advanced-ci.md、advanced-benchmark.md
recipe-*	框架专属配方（5 个）	recipe-vue.md、recipe-wasm.md
reference-*	CLI 与 API 参考	reference-cli.md

这种"一个文件只讲一个主题"（keep it focused, one topic per file）的拆分方式，是典型的为 LLM 检索优化的文档组织形式：代理遇到某类问题时，只需加载对应的前缀文件即可获得高信噪比的上下文，而不必读取整篇大文档。

4. 技能的触发场景与示例提示词

README 的 Usage 一节说明，安装后代理会在以下场景中自动运用 tsdown 知识：构建 TypeScript/JavaScript 库、为库项目配置 bundler、设置类型声明生成、多格式构建（ESM、CJS、IIFE、UMD）、从 tsup 迁移、构建框架组件库。

README 给出的 5 个示例提示词，恰好覆盖了 AIRI 仓库中真实存在的构建需求形态：

Set up tsdown to build my TypeScript library with ESM and CJS formats
Configure tsdown to generate type declarations and bundle for browsers
Add React support to my tsdown config with Fast Refresh
Help me migrate from tsup to tsdown
Set up a monorepo build with tsdown workspace support

其中第一条（ESM + CJS 双格式 + 类型声明）正是 AIRI 库包最典型的配置形态。技能配套的迁移能力由专门的 tsdown-migrate 技能承担，SKILL.md 中也明确提示：需要完整选项映射的迁移协助时，应安装 --skill tsdown-migrate 对应的独立技能，并可通过 npx tsdown-migrate CLI 自动执行迁移。

5. 关键运行前提：Node.js 22.18+ 只是构建期要求

SKILL.md 中一个容易被误解、因此被单独强调的事实是：tsdown 要求 Node.js 22.18.0 或更高版本才能运行，但这仅是**构建期（build-time）**要求；打包产物可以通过 target 选项针对低得多的 Node.js 版本。若库需要支持 Node 18/20，推荐做法是：

• 在 CI 中用 Node.js 22+ 构建，并设置 target: 'node18' 或 target: 'node20'；
• 在低版本 Node.js 上测试构建产物（或打包好的 tarball），例如用矩阵任务在 Node 18 / 20 / 22 上运行已发布包的测试。

这条约束在 AIRI 仓库中有直接印证：packages/server-runtime/tsdown.config.ts 和 services/computer-use-mcp/tsdown.config.ts 都显式配置了 target: 'node18'——构建工具链跑在较新 Node 上，产物却面向 Node 18 运行时，正是技能文档所描述的"构建期/运行期解耦"策略的落地。

6. 技能知识在 AIRI 单仓中的落地证据

README 描述的知识点并非空谈，仓库中 29 个包/服务各自维护了 tsdown.config.ts。以下三个实例分别对应技能文档中不同章节讲解的配置能力。

6.1 命名多入口（对应 "Multiple Entry Points" 模式）

packages/server-runtime/tsdown.config.ts 使用对象形式 entry 来定义三个子路径入口：

import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: {
    'index': 'src/index.ts',
    'server': 'src/server/index.ts',
    'bin/run': 'src/bin/run.ts',
  },
  target: 'node18',
  outDir: 'dist',
  clean: true,
  dts: true,
})

这里同时用到了技能 Build Options 表中讲解的 target（运行环境目标）、outDir（输出目录，对应 references/option-output-directory.md）、clean（输出清理，对应 references/option-cleaning.md）和 dts（类型声明生成，对应 references/option-dts.md）。对象式 entry 会产出 dist/index、dist/server、dist/bin/run 多组入口，与 package.json 的 exports 字段配合，这正是技能 Best Practices 第 6 条"自动生成 package.json exports"所服务的场景。

6.2 数组式多入口（对应 "Basic Library Bundle" 模式）

packages/plugin-sdk/tsdown.config.ts 展示了一个更简的形态——数组形式 entry、单一 esm 格式：

import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: [
    'src/index.ts',
    'src/plugin-host/index.ts',
    'src/plugin-host/runtimes/node/index.ts',
    'src/plugin-host/runtimes/web/index.ts',
  ],
  dts: true,
  format: 'esm',
})

从源码结构看，plugin-sdk 需要同时分发 Node 与 Web 两个 runtime 宿主入口（src/plugin-host/runtimes/node 与 src/plugin-host/runtimes/web），这正是技能所讲的"多入口 + 声明文件"库分发模式的真实用例。

6.3 技能知识如何驱动仓库的日常构建

AGENTS.md（项目级代理指南）定义了 AIRI 的构建约定：统一使用 pnpm workspace 过滤器执行 pnpm -F <package.json name> build。以 packages/better-ws/package.json 为例，其 build 脚本就是裸的 tsdown 命令——依赖 tsdown 自动发现同目录的 tsdown.config.ts（references/option-config-file.md 中描述的自动发现机制：tsdown.config.ts 等 9 种文件名按序查找）。这意味着仓库里的每个构建脚本几乎零配置，而"零配置为何可行"的答案正由技能包中的配置文档体系来支撑——当代理需要为新包创建 tsdown.config.ts 或排查构建问题时，它会读取对应前缀的 reference 文档，而不是凭空猜测。

7. 配置文件的加载与高级能力速览

结合技能文档 references/option-config-file.md，AIRI 各包使用的 tsdown.config.ts 属于首选的 TypeScript 配置格式（获得类型检查与自动补全）。该文档还覆盖了几项对 monorepo 尤其重要的能力：

配置查找顺序与优先级（优先级从高到低）：CLI 选项 > --config 指定的配置文件 > 自动发现的配置文件 > package.json 的 tsdown 字段 > 默认值。

动态配置：defineConfig 接受函数，可按 CLI 传入的选项做条件构建——这正是 SKILL.md 中 "Development vs Production" 模式的来源：

export default defineConfig((options) => {
  const isDev = options.watch
  return {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    minify: !isDev,
    sourcemap: isDev,
  }
})

Workspace / Monorepo：根配置可用 glob 一次构建多个包，各包还可用自己的配置文件做局部覆盖（Per-Package Override）：

export default defineConfig({
  workspace: 'packages/*',
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
})

AIRI 当前采用"每包一份 tsdown.config.ts"的分散式布局（29 处配置文件分布在 packages/、plugins/、services/、integrations/vscode/、server/packages/ 下），而非单一 workspace 根配置；从配置文件内容看，各包配置高度趋同（entry + dts + 少量 target/outDir/clean），与 AGENTS.md 中"avoid one-off patterns、用 pnpm 过滤器按包构建"的工程约定一致。

配置加载器：除默认 auto loader（优先原生 TS 支持，回退 unrun）外，还可通过 --config-loader native|tsx|unrun 指定加载方式；另有实验性的 --from-vite 可复用 Vite/Vitest 配置中的 resolve 与 plugins。

8. 技能包的维护与更新流程

references/README.md 的 "Updating Existing Files" 一节定义了技能内容过时的更新流程：当上游 tsdown 文档变更时，通过 git diff <sha>..HEAD -- docs/ 检查差异，更新受影响的 reference 文件，必要时同步 SKILL.md，并更新 GENERATION.md 中的 SHA。AIRI 仓库的 SYNC.md（记录来源 SHA 与同步日期）加上 skills-lock.json 的 computedHash，恰好构成了这条更新流程的消费端：同步者负责推进 SHA，锁定文件负责声明当前内容的指纹，两者共同保证"技能内容与某个上游版本严格对应"。

9. 小结：技能包作为"bundler 领域知识的可检索容器"

回到 README.md 的主线，这套 tsdown Skills 的价值可以归纳为三点，且每一点在 AIRI 仓库中都有对应物：

1. 知识结构化：38 个按 guide-* / option-* / advanced-* / recipe-* / reference-* 前缀组织的参考文件，让代理能按需加载高信噪比的 tsdown 知识（README "What's Included" 一节所列 9 类知识全部有对应文档落地）；
2. 知识可审计：SYNC.md 的 SHA/日期 + skills-lock.json 的哈希，把"代理学到的东西"变成了可版本化、可校验的仓库资产；
3. 知识与实践闭环：仓库 29 个 tsdown.config.ts（如 packages/server-runtime/tsdown.config.ts、packages/plugin-sdk/tsdown.config.ts）与 packages/better-ws/package.json 中的 "build": "tsdown" 脚本，构成技能知识最直接的验证场——技能文档里讲解的每个选项，几乎都能在某个真实包配置中找到使用实例。

对于在 monorepo 中引入 AI 编码代理的团队，这套"同步技能进仓库 + 哈希锁定 + 按主题切分参考文档"的做法，是一个值得参考的通用模式：它让代理的构建配置能力不再依赖临场发挥，而是由与代码库一同演进的可检索知识来约束。