refactor: 精简重构 Bun Catalog 依赖管理指南，提升可读性与使用规范

- 精简并重构 Bun Catalog 依赖管理指南，突出核心概念与操作流程，优化结构提升可读性，明确使用规范与常见问题解决方案。

skills/bun-catalog-package/SKILL.md

@@ -1,159 +1,103 @@
 ---
 name: bun-catalog-package
-description: Bun 包管理器中使用 catalog 功能添加依赖包的标准流程指南。当用户需要在 Bun monorepo 项目中使用 catalog 功能添加或管理依赖包时使用此技能。适用于解决 Bun 不支持在子包直接安装 catalog 依赖的限制问题。
+description: Bun Catalog 依赖管理指南。在 Bun monorepo 项目中使用 catalog 功能统一管理依赖版本。
 ---
 
-# Bun Catalog 包管理流程
+# Bun Catalog 依赖管理
 
-## 问题背景
+## 什么是 Catalog
 
-Bun 包管理器目前**不支持**在子包（workspace）中直接安装并自动添加到 catalog 的包。如果在子包目录执行 `bun add <包名>`，包会直接添加到子包的 `package.json`，而不会使用 catalog 引用。
+Bun Catalog 是 monorepo 中统一管理依赖版本的机制。所有版本定义在根 `package.json` 的 `catalog` 字段，子包通过 `catalog:` 协议引用。
 
-## 标准操作流程
+## 快速上手
 
-### 1. 查询包的最新版本
+### 添加新依赖（两步）
 
 ```bash
-bun info <包名>
+# 1. 查询最新版本
+bun info <package-name> version
+# 输出: 4.3.6
+
+# 2. 在子包中安装
+cd apps/server
+bun add <package-name>@catalog:
 ```
 
-**示例**:
+**前提**: 根 `package.json` 的 `catalog` 中已有该包。如果没有，先手动添加。
+
+### 添加 Catalog 中不存在的包（三步）
+
 ```bash
-bun info zod
+# 1. 查询最新版本
-# 输出示例：
+bun info <package-name> version
-# zod@4.0.0 - TypeScript-first schema validation
+
+# 2. 在根 package.json 的 catalog 中添加
+# "catalog": {
+#   "<package-name>": "^x.y.z"
+# }
+
+# 3. 在子包中安装
+cd apps/server
+bun add <package-name>@catalog:
 ```
 
-从输出中获取包名和最新版本号（例如 `zod@4.0.0`）。
+## 常用命令
 
-### 2. 添加到根 package.json 的 catalog
+| 命令 | 用途 |
+|------|------|
+| `bun info <pkg> version` | 查询最新版本（仅版本号） |
+| `bun info <pkg>` | 查询完整包信息 |
+| `bun add <pkg>@catalog:` | 在子包中安装 catalog 依赖 |
+| `bun run install` | 安装所有依赖 |
+| `bun outdated` | 检查过时依赖 |
 
-在项目根目录的 `package.json` 中找到 `catalog` 字段，手动添加包及其版本：
+## 文件结构示例
 
+**根 package.json**:
 ```json
 {
   "workspaces": ["apps/*", "packages/*"],
   "catalog": {
-    "react": "^18.3.1",
+    "react": "^19.0.0",
-    "typescript": "^5.0.0",
+    "zod": "^3.24.0",
-    "zod": "^4.0.0"  // 新增的包
+    "@tanstack/react-query": "^5.0.0"
   }
 }
 ```
 
-**注意事项**:
+**子包 package.json** (`apps/server/package.json`):
-- 使用 `^` 前缀表示自动更新小版本（推荐）
-- 也可以使用精确版本号（不加 `^`）锁定版本
-
-### 3. 在子包中引用 catalog
-
-在需要使用该包的子包（如 `apps/api/package.json`）中，添加 catalog 引用：
-
 ```json
 {
-  "name": "@my-project/api",
+  "name": "@myapp/server",
   "dependencies": {
-    "hono": "catalog:",
+    "react": "catalog:",
-    "zod": "catalog:"  // 引用 catalog 中的 zod
+    "zod": "catalog:"
   }
 }
 ```
 
-**格式说明**:
-- 使用 `"包名": "catalog:"` 格式
-- **不需要**指定版本号，会自动使用根 `package.json` 中 catalog 定义的版本
-
-### 4. 安装依赖
-
-在项目根目录执行：
-
-```bash
-bun install
-```
-
-Bun 会：
-1. 解析 catalog 中定义的版本
-2. 将包安装到子包的 `node_modules`
-3. 保持子包 `package.json` 中的 `catalog:` 引用不变
-
-## 完整示例
-
-假设要在 `apps/api` 中添加 `@hono/zod-validator` 包：
-
-```bash
-# 步骤 1: 查询版本
-bun info @hono/zod-validator
-# 输出: @hono/zod-validator@0.4.1
-
-# 步骤 2: 编辑根 package.json
-# {
-#   "catalog": {
-#     "@hono/zod-validator": "^0.4.1"
-#   }
-# }
-
-# 步骤 3: 编辑 apps/api/package.json
-# {
-#   "dependencies": {
-#     "@hono/zod-validator": "catalog:"
-#   }
-# }
-
-# 步骤 4: 安装
-bun install
-```
-
-## 优势
-
-使用 catalog 管理依赖的好处：
-
-1. **版本统一**: 所有子包使用相同版本，避免版本冲突
-2. **集中管理**: 在根 `package.json` 一处更新版本
-3. **减少重复**: 子包中只需写 `catalog:`，无需重复版本号
-4. **自动同步**: 更新 catalog 版本后，所有引用自动生效
-
 ## 注意事项
 
-- ✅ 始终在**根目录**执行 `bun install`
+| 正确 | 错误 |
-- ✅ catalog 定义在**根 `package.json`**
+|------|------|
-- ✅ 子包中使用 `"catalog:"` 引用（注意有冒号）
+| `bun add zod@catalog:` | `bun add zod@latest` (绕过 catalog) |
-- ❌ 不要在子包目录直接 `bun add <包名>`（会绕过 catalog）
+| `"zod": "catalog:"` | `"zod": "^3.24.0"` (硬编码版本) |
-- ❌ 不要在子包 `package.json` 中写具体版本号（如 `"zod": "^4.0.0"`）
+| 在根目录定义版本 | 在子包定义版本 |
+
+## 为什么用 Catalog
+
+- **版本统一**: 所有子包使用相同版本，避免冲突
+- **集中管理**: 升级只需改根 `package.json`
+- **减少重复**: 子包无需重复写版本号
 
 ## 疑难排查
 
-### 问题：子包中显示 "catalog: 未找到"
+**"catalog: 未找到"**
+→ 根 `package.json` 的 `catalog` 中没有该包，先手动添加
 
-**原因**: 根 `package.json` 的 `catalog` 字段中没有该包
+**版本不是最新**
-
+→ `bun info <pkg> version` 查最新版本，更新 catalog，重新 `bun run install`
-**解决**: 检查根 `package.json`，确保包已添加到 `catalog` 对象中
-
-### 问题：安装后版本不是最新的
-
-**原因**: catalog 中定义的版本过旧
-
-**解决**: 
-1. 运行 `bun info <包名>` 查看最新版本
-2. 更新根 `package.json` 中 catalog 的版本号
-3. 重新运行 `bun install`
-
-## 相关命令速查
-
-```bash
-# 查询包信息（版本、描述等）
-bun info <包名>
-
-# 查看已安装包的版本
-bun pm ls <包名>
-
-# 更新所有依赖到 catalog 定义的版本
-bun install
-
-# 查看 catalog 配置
-cat package.json | grep -A 20 "catalog"
-```
 
 ---
 
-**最后更新**: 2026-01-22  
 **适用版本**: Bun 1.0+