arch-upkeep

arch-upkeep

arch-upkeep 是一个元架构技能，用于让现有项目与规范化的起始模板栈保持一致：

• arch-tsdown-monorepo — 面向 TS 库的 pnpm monorepo，每个包使用 tsdown
• arch-tsdown — 使用 tsdown 的单包 TS 库
• arch-tsdown-cli — 基于 tsdown 构建的 CLI 应用
• arch-unplugin — 以 unplugin 形式构建的库（Vite/Rollup/Webpack/ESBuild）
• arch-webext-vue — 使用 Vue 的浏览器扩展
• arch-vscode — VS Code 扩展

当项目已存在，并且你希望执行以下操作时，请使用此技能：

• 识别它当前匹配哪种架构（lib / CLI / monorepo / webext / vscode / unplugin / 混合）
• 规划向某个规范化 arch-* 起始模板的迁移
• 增量升级工具链、脚本和 CI，而不重写应用逻辑

此技能不会详细重新规定每种架构——它帮助你选择应应用哪个 arch 技能以及以什么顺序应用。

快速开始

1. 使用 1. 检测当前架构中的检查项对仓库进行分类。
2. 使用 2. 选择目标架构技能将其映射到目标技能。
3. 通过 2.1 检查并安装所需技能确保已安装所需的 arch-* 技能。
4. 使用 3. 迁移策略（增量）和 4. 特定架构注意事项来规划增量迁移。
5. 使用 5. 检查清单：在仓库上运行“架构维护”中的清单运行一次维护。

1. 检测当前架构

首先对仓库进行分类。使用这些快速启发式判断（你可以应用多个判断，项目可能是“monorepo + CLI”等）：

• Monorepo（arch-tsdown-monorepo 候选）

  • 有 pnpm-workspace.yaml 或 packages/*、apps/* 或类似布局
  • packages/ 或 apps/ 下有多个 package.json 文件
  • 根目录有共享工具链配置（eslint.config.*、vitest.config.*、tsconfig.base.json 等）

• 单个 TS 库（arch-tsdown 候选）

  • 根目录只有一个 package.json
  • 库风格的导出（main、module、types，可能还有 exports）
  • 没有 bin 入口点，没有浏览器 manifest，没有 VS Code 扩展 manifest

• CLI（arch-tsdown-cli 候选）

  • 根 package.json 中的 "bin" 或 "package.json#exports" 指向 CLI 入口
  • 在入口文件中使用 #!/usr/bin/env node
  • 通常依赖 cac、commander、yargs 等

• 基于 unplugin 的库（arch-unplugin 候选）

  • 依赖 unplugin
  • 导出 createUnplugin，或有 src/core/、src/vite.ts、src/webpack.ts 等文件
  • 面向打包器（Vite/Rollup/Webpack/ESBuild）

• 浏览器扩展 + Vue（arch-webext-vue 候选）

  • 有 manifest.json/manifest.v3.json（Chrome/Firefox 扩展）
  • 用于 popup/options 或内容脚本的 Vue SPA
  • 围绕 Web 扩展开发的构建工具链（web-ext、wxt 或自定义脚本）

• VS Code 扩展（arch-vscode 候选）

  • 有带 "contributes"、"activationEvents"、"engines.vscode" 的 package.json
  • 有 src/extension.ts 或类似的激活入口

一旦你知道它“主要是什么”，就选择一个主要架构作为升级目标。如果仓库是混合的（例如带一个 CLI 包的 monorepo），请将 arch-tsdown-monorepo 与相关的按包技能（arch-tsdown、arch-tsdown-cli 等）配对使用。

2. 选择目标架构技能

将你的分类映射到规范技能：

• pnpm 多包仓库 → 从 arch-tsdown-monorepo 开始
• 单个 TS 库 → arch-tsdown
• 命令行（单个或位于 monorepo 包内）→ arch-tsdown-cli
• unplugin 库 → arch-unplugin（通常位于 arch-tsdown 或 monorepo 设置内）
• 浏览器扩展 + Vue → arch-webext-vue（应用层）加上用于任何共享库的 arch-tsdown
• VS Code 扩展 → arch-vscode（扩展应用）加上用于共享库的 arch-tsdown

然后：

1. 打开对应的 arch-* 技能。
2. 将其 “overview” / “core” 参考用作你希望现有仓库收敛到的目标设计。
3. 规划增量迁移：先配置和脚本，然后是 CI，最后是发布自动化。

2.1 检查并安装所需技能

因为 arch-upkeep 只是一个编排器，它期望具体的 arch-* 技能在 Agent 环境中已安装且可用。

推荐流程：

1. 在你的 Agent 运行时中列出已安装的技能

   • 使用你平台的 “list skills” 命令 / UI（例如，查找 arch-tsdown-monorepo、arch-tsdown、arch-tsdown-cli、arch-unplugin、arch-webext-vue、arch-vscode）。
   • 如果目标架构技能已经存在，你可以直接调用它。

2. 如果缺少所需技能，请按名称安装

   • 从 Agent Skills 目录（或你平台的市场）中，搜索确切名称，例如 arch-tsdown-monorepo。
   • 将其安装到当前 Agent 配置文件 / 工作区。

3. 继续之前验证安装

   • 重新运行 “list skills” 视图，确认该技能出现并已启用。
   • 可选地打开其 SKILL.md（或 UI 中的技能详情），以确认版本和范围。

4. 在一次 upkeep 会话中组合多个技能

   • 对于 monorepo + 命令行：在命令行包上使用 arch-tsdown-monorepo + arch-tsdown-cli，并在共享库上使用 arch-tsdown。
   • 对于 带共享库的 VS Code 扩展：在扩展宿主上使用 arch-vscode + 在共享模块上使用 arch-tsdown。
   • 对于 Web 扩展 + 共享 TS 库：在扩展应用上使用 arch-webext-vue + 在可复用包上使用 arch-tsdown。

只有在相关技能安装并验证后，才应开始应用下面的迁移步骤。

3. 迁移策略（增量式）

通用原则：

• 不要重写应用逻辑。 只替换基础设施（构建、测试、lint、CI、发布）。
• 一次只处理一层。 如果可以拆分，避免在单个 PR 中同时更改 bundler、测试运行器和 tsconfig。
• 保持 Git 历史可读。 将“工具链迁移”与“代码修复”的提交分开。

推荐顺序：

1. 规范化包布局

   • 对于 monorepo：按照 arch-tsdown-monorepo 对齐 packages/* 布局、根 package.json、workspace 版本范围、pnpm catalogs。
   • 对于单包：按照 arch-tsdown 对齐文件夹结构（src/、dist/、tests/）、tsconfig 命名等。

2. 将构建迁移到 tsdown（如适用）

   • 用目标 skill 中的 tsdown 配置替换旧构建脚本（tsc、rollup、tsup 等）。
   • 确保 package.json#exports、main/module/types 和 files 字段与目标模式一致。

3. 对齐测试与 lint

   • 迁移到相关 arch skill 推荐的测试运行器（Vitest）和 ESLint 设置。
   • 对于 monorepo，将配置集中到根目录，并在需要时按包覆盖。

4. 同步脚本

   • 统一使用目标架构中的脚本名称（build、dev、test、lint、typecheck、release 等）。
   • 对于 monorepo，优先使用根脚本，通过 pnpm -r 或 pnpm --filter 运行。

5. 升级 CI 与发布

   • 采用相关 arch skill 中的 GitHub Actions / 发布工作流。
   • 如适用，迁移到 npm Trusted Publisher、基于 tag 的发布以及 bumpp 或类似方案。

6. 清理

   • 在新流水线通过后，移除过时的配置、脚本和未使用的 devDependencies。

4. 特定架构说明

• 当目标为 arch-tsdown-monorepo 时：

  • 将工具链（ESLint、Vitest、TS 基础配置）集中到根目录。
  • 将跨包依赖转换为 workspace:* 版本范围。
  • 使每个包都能用 tsdown 独立构建。

• 当目标为 arch-tsdown 或 arch-tsdown-cli 时：

  • 将该包视为规范的 TS 库/CLI；尽可能保持 src/ 干净且无副作用。
  • 确保二进制入口点是小型的引导文件，从内部模块导入。

• 当目标为 arch-unplugin 时：

  • 保持 unplugin 核心小巧且可组合。
  • 通过统一的 unplugin API 为不同 bundler（Vite、Rollup、Webpack、ESBuild）提供清晰的导出。

• 当目标为 arch-webext-vue 时：

  • 将应用 UI（Vue）与 background/service worker 逻辑以及共享工具分离。
  • 对于可在扩展之外复用的逻辑，优先使用共享 TS 库（使用 arch-tsdown）。

• 当目标为 arch-vscode 时：

  • 保持扩展宿主代码（激活、命令）轻量。
  • 尽可能将重度逻辑移到共享 TS 库中。

5. 清单：在仓库上执行 “arch upkeep”

将此作为可重复的工作流：

1. 分类架构（monorepo / lib / CLI / unplugin / webext / vscode）。
2. 选择与期望终态匹配的主要 arch-* skill。
3. 阅读其概览/核心参考，并写下目标结构和脚本。
4. 规划增量步骤（布局 → 构建 → 测试/lint → CI → 发布）。
5. 应用更改，同时保持应用逻辑不变。
6. 在新流水线通过后删除旧工具链。

完成这些之后，项目的外观和行为应该就像最初从所选 starter 脚手架生成的一样，这会让未来的维护和上手容易得多。