@42ailab/42plugin 0.1.22 → 0.1.23

package/README.md

@@ -109,7 +109,7 @@ bun run build
 ```
 
 选项：
-- `-g, --global`：仅下载到缓存，不链接到当前项目
+- `-g, --global`：安装到全局目录 (~/.42plugin/global/)
 - `-k, --kit`：安装该插件所属的整个套包
 - `--optional`：安装套包时包含可选项
 - `--force`：强制重新下载
@@ -119,11 +119,19 @@ bun run build
 ### 管理
 
 ```bash
-42plugin list                        # 查看已安装
-42plugin list --type skill --json
-42plugin uninstall <full_name>       # 卸载
-42plugin uninstall <full_name> --purge
-42plugin version                     # 版本
+# 查看插件
+42plugin list                        # 当前项目已安装的插件
+42plugin list --global               # 全局安装的插件 (~/.claude/)
+42plugin list --all                  # 所有项目 + 全局的插件
+42plugin list --type skill --json    # 筛选类型，输出 JSON
+
+# 卸载插件
+42plugin uninstall <full_name>            # 从当前项目卸载
+42plugin uninstall <full_name> --global   # 从全局目录卸载
+42plugin uninstall <full_name> --purge    # 卸载并清除下载缓存
+
+# 版本
+42plugin version
 ```
 
 ### 发布（开发中）
@@ -140,12 +148,30 @@ bun run build
 
 ## 数据存储
 
-| 类型 | 路径 |
-|------|------|
-| 数据库 | `~/.42plugin/local.db`（Windows: `%APPDATA%/42plugin/local.db`） |
-| 缓存 | `~/.42plugin/cache` |
-| 登录凭证 | `~/.42plugin/secrets.json`（权限 600） |
-| 项目链接 | `.claude/`（项目目录下） |
+| 类型 | 路径 | 说明 |
+|------|------|------|
+| 数据库 | `~/.42plugin/local.db` | 本地 SQLite（Windows: `%APPDATA%/42plugin/`） |
+| 下载缓存 | `~/.42plugin/cache/` | 插件原始文件缓存 |
+| 登录凭证 | `~/.42plugin/secrets.json` | 权限 600 |
+| 全局安装 | `~/.claude/` | 对所有项目生效，Claude Code 可识别 |
+| 项目安装 | `./.claude/` | 仅对当前项目生效 |
+
+### 全局 vs 项目安装
+
+```
+~/.claude/                    # 全局目录，对所有项目生效
+├── skills/
+├── agents/
+└── ...
+
+/path/to/project/.claude/     # 项目目录，仅对该项目生效
+├── skills/
+├── agents/
+└── ...
+```
+
+- **全局安装** (`--global`)：插件安装到 `~/.claude/`，所有项目都能使用
+- **项目安装**（默认）：插件安装到当前项目的 `.claude/`，仅当前项目可用
 
 ## 本地数据库表（SQLite）
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@42ailab/42plugin",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "活水插件",
   "type": "module",
   "main": "src/index.ts",

package/src/api.ts

@@ -601,6 +601,7 @@ class ApiClient {
         description: params.description,
         tags: params.tags,
         visibility: params.visibility,
+        doc_content: params.docContent,
       },
     });
 

package/src/cli.ts

@@ -14,6 +14,7 @@ import {
   checkCommand,
 } from './commands';
 import { setupAuthHook } from './auth-middleware';
+import { checkForUpdates, checkForUpdatesSync } from './update-checker';
 
 // 版本号处理：
 // - Homebrew（编译后）：构建时通过 --define __VERSION__ 注入
@@ -58,11 +59,22 @@ program.addCommand(setupCommand);
 program
   .command('version')
   .description('显示版本信息')
-  .action(() => {
+  .option('--check', '检查是否有新版本')
+  .action(async (options: { check?: boolean }) => {
     console.log(`42plugin v${VERSION}`);
+    if (options.check) {
+      console.log();
+      await checkForUpdatesSync(VERSION);
+    }
   });
 
 // 注册全局认证 Hook
 setupAuthHook(program);
 
+// 注册版本更新检查 Hook（命令执行后触发）
+program.hook('postAction', () => {
+  // 非阻塞检查，不影响命令执行
+  checkForUpdates(VERSION);
+});
+
 export { program };

package/src/commands/install.ts

@@ -8,7 +8,7 @@ import ora from 'ora';
 import path from 'path';
 import os from 'os';
 import { confirm } from '@inquirer/prompts';
-import { api, QuotaExceededError } from '../api';
+import { api, ApiError, QuotaExceededError } from '../api';
 import fs from 'fs/promises';
 import {
   getOrCreateProject,
@@ -17,19 +17,63 @@ import {
   resolveCachePath,
   checkInstallConflict,
   removeInstallation,
+  getSessionToken,
 } from '../db';
 import { config } from '../config';
 import { parseTarget, getInstallPath, formatBytes, getTypeIcon } from '../utils';
 import { TargetType, type PluginDownloadInfo } from '../types';
 
 export const installCommand = new Command('install')
-  .description('安装插件或套包')
-  .argument('<target>', '安装目标 (author/name 或 author/kit/slug)')
-  .option('-g, --global', '仅下载到缓存，不链接到项目')
+  .description('安装插件或套包\n\n示例:\n  42plugin install alice/smart-reviewer     安装插件\n  42plugin install alice/kit/dev-tools      安装套包\n  42plugin install like                     安装您的收藏')
+  .argument('<target>', '安装目标 (author/name, author/kit/slug, 或 like)')
+  .option('-g, --global', `安装到全局目录，对所有项目生效 (~/.claude/)`)
   .option('-f, --force', '强制重新下载')
   .option('--no-cache', '跳过缓存检查')
   .option('--optional', '安装套包时包含可选插件')
   .action(async (target, options) => {
+    // 保留名称检测和扩展（虚拟收藏 Kit）
+    const RESERVED_KIT_NAMES = ['like', 'liked', 'starred', 'favorites', 'favourite', 'favourites'];
+    const normalizedTarget = target.trim().toLowerCase();
+
+    // 检测是否为单段保留名称（简化格式）
+    if (!normalizedTarget.includes('/') && RESERVED_KIT_NAMES.includes(normalizedTarget)) {
+      // 需要登录才能使用收藏功能
+      const sessionToken = await getSessionToken();
+      if (!sessionToken) {
+        console.error(chalk.red('\n使用收藏功能需要先登录'));
+        console.log(chalk.gray('执行 42plugin auth 登录'));
+        process.exit(1);
+      }
+
+      // 验证登录状态并获取 username（token 已在全局 hook 中注入）
+      let username: string | null = null;
+      try {
+        const session = await api.getSession();
+        const emailPrefix = session.user.email?.split('@')[0]?.trim();
+        username = session.user.username || session.user.name || (emailPrefix || null);
+
+        if (!username || username.trim() === '') {
+          console.error(chalk.red('\n无法获取用户名，请设置用户名后重试'));
+          console.log(chalk.gray('访问 42plugin.com 设置用户名'));
+          process.exit(1);
+        }
+      } catch (error) {
+        if (error instanceof ApiError && error.statusCode === 401) {
+          console.error(chalk.red('\n登录已过期，请重新登录'));
+          console.log(chalk.gray('执行 42plugin auth 登录'));
+        } else {
+          console.error(chalk.red('\n验证登录状态失败'));
+          console.log(chalk.gray(`错误: ${(error as Error).message}`));
+          console.log(chalk.gray('请检查网络连接或稍后重试'));
+        }
+        process.exit(1);
+      }
+
+      // 扩展为完整格式
+      target = `${username}/kit/${normalizedTarget}`;
+      console.log(chalk.gray(`\n安装您的收藏: ${username}/${normalizedTarget}\n`));
+    }
+
     // token 已在全局 hook 中注入
     try {
       // 检测是否在 home 目录
@@ -38,18 +82,19 @@ export const installCommand = new Command('install')
       const isHomeDir = currentPath === homePath;
 
       if (isHomeDir && !options.global) {
+        console.log(chalk.yellow('\n⚠ 您当前在用户根目录'));
+        console.log(chalk.gray('  • 全局安装：插件对所有项目生效，存放在 ~/.claude/'));
+        console.log(chalk.gray('  • 项目安装：插件仅对当前项目生效，存放在 ./.claude/\n'));
+
         const answer = await confirm({
-          message: '您当前在根目录，是否将插件安装到全局用户目录？',
+          message: '是否安装到全局目录？',
           default: true,
         });
 
         if (answer) {
           options.global = true;
-          // 确保全局目录存在
-          await fs.mkdir(config.globalDir, { recursive: true });
-          console.log(chalk.gray('将安装到全局目录: ~/.42plugin/global/'));
         } else {
-          console.log(chalk.yellow('提示: 建议在具体项目目录下执行安装命令'));
+          console.log(chalk.yellow('提示: 请进入具体项目目录后再执行安装命令'));
           return;
         }
       }
@@ -163,8 +208,9 @@ async function installPlugin(
     );
 
     if (options.global) {
-      console.log(chalk.green('✓ 已安装到全局用户目录'));
-      console.log(chalk.gray(`  → ~/.42plugin/global/${downloadInfo.installPath}`));
+      console.log(chalk.green('✓ 已全局安装，对所有项目生效'));
+      console.log(chalk.gray(`  → ~/.claude/${downloadInfo.installPath}`));
+      console.log(chalk.gray('  提示: 使用 42plugin list --global 查看全局插件'));
     } else {
       console.log(chalk.green(`✓ 已安装到当前项目: ${path.basename(projectPath)}`));
       console.log(chalk.gray(`  → ${downloadInfo.installPath}`));
@@ -316,7 +362,8 @@ async function installKit(
     console.log();
     if (failed === 0) {
       if (options.global) {
-        console.log(chalk.green(`✓ 已安装 ${installed} 个插件到全局用户目录`));
+        console.log(chalk.green(`✓ 已全局安装 ${installed} 个插件，对所有项目生效`));
+        console.log(chalk.gray('  提示: 使用 42plugin list --global 查看全局插件'));
       } else {
         console.log(chalk.green(`✓ 已安装 ${installed} 个插件到当前项目`));
       }

package/src/commands/list.ts

@@ -4,56 +4,173 @@
 
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { getInstallations } from '../db';
+import { getInstallations, getAllInstallations } from '../db';
+import { config, isGlobalDir } from '../config';
 import { getTypeIcon, formatRelativeTime } from '../utils';
 import type { PluginType } from '../types';
 
 export const listCommand = new Command('list')
   .alias('ls')
-  .description('查看当前项目已安装的插件')
+  .description('查看已安装的插件')
+  .option('-g, --global', '显示全局安装的插件 (~/.claude/)')
+  .option('-a, --all', '显示所有项目的插件（包括全局）')
   .option('-t, --type <type>', '筛选类型 (skill, agent, command, hook, mcp)')
   .option('--json', '输出 JSON 格式')
   .action(async (options) => {
     try {
-      let installations = await getInstallations(process.cwd());
-
-      // 类型筛选
-      if (options.type) {
-        installations = installations.filter((i) => i.type === options.type);
+      if (options.all) {
+        await listAllProjects(options);
+      } else if (options.global) {
+        await listGlobalPlugins(options);
+      } else {
+        await listCurrentProject(options);
       }
+    } catch (error) {
+      console.error(chalk.red((error as Error).message));
+      process.exit(1);
+    }
+  });
 
-      if (options.json) {
-        console.log(JSON.stringify(installations, null, 2));
-        return;
-      }
+async function listCurrentProject(options: { type?: string; json?: boolean }): Promise<void> {
+  const projectPath = process.cwd();
+  let installations = await getInstallations(projectPath);
 
-      if (installations.length === 0) {
-        console.log(chalk.yellow('当前项目未安装任何插件'));
-        console.log(chalk.gray('执行 42plugin install <name> 安装插件'));
-        return;
-      }
+  // 类型筛选
+  if (options.type) {
+    installations = installations.filter((i) => i.type === options.type);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(installations, null, 2));
+    return;
+  }
+
+  if (installations.length === 0) {
+    console.log(chalk.yellow('当前项目未安装任何插件'));
+    console.log(chalk.gray('执行 42plugin install <name> 安装插件'));
+    console.log(chalk.gray('执行 42plugin list --global 查看全局插件'));
+    return;
+  }
+
+  console.log(chalk.gray(`当前项目已安装 ${installations.length} 个插件:\n`));
+
+  for (const item of installations) {
+    const icon = getTypeIcon(item.type);
+    const time = formatRelativeTime(item.installedAt);
+
+    console.log(`${icon} ${chalk.cyan.bold(item.fullName)} ${chalk.gray(`v${item.version}`)}`);
+    console.log(chalk.gray(`  → ${item.linkPath}`));
+
+    // 解析所属套包：fullName 格式为 author/kit/plugin
+    const parts = item.fullName.split('/');
+    if (parts.length >= 3) {
+      const kitName = `${parts[0]}/${parts[1]}`;
+      console.log(chalk.gray(`  所属套包: ${kitName}`));
+    }
+
+    console.log(chalk.gray(`  安装于 ${time}`));
+    console.log();
+  }
+}
+
+/**
+ * 列出全局安装的插件
+ */
+async function listGlobalPlugins(options: { type?: string; json?: boolean }): Promise<void> {
+  let installations = await getInstallations(config.globalDir);
+
+  // 类型筛选
+  if (options.type) {
+    installations = installations.filter((i) => i.type === options.type);
+  }
 
-      console.log(chalk.gray(`已安装 ${installations.length} 个插件:\n`));
+  if (options.json) {
+    console.log(JSON.stringify(installations, null, 2));
+    return;
+  }
 
-      for (const item of installations) {
-        const icon = getTypeIcon(item.type);
-        const time = formatRelativeTime(item.installedAt);
+  if (installations.length === 0) {
+    console.log(chalk.yellow('未安装任何全局插件'));
+    console.log(chalk.gray('执行 42plugin install <name> --global 安装全局插件'));
+    return;
+  }
 
-        console.log(`${icon} ${chalk.cyan.bold(item.fullName)} ${chalk.gray(`v${item.version}`)}`);
-        console.log(chalk.gray(`  → ${item.linkPath}`));
+  console.log(chalk.cyan('📍 全局插件') + chalk.gray(' (~/.claude/) - 对所有项目生效\n'));
+  console.log(chalk.gray(`共 ${installations.length} 个插件:\n`));
 
-        // 解析所属套包：fullName 格式为 author/kit/plugin
-        const parts = item.fullName.split('/');
-        if (parts.length >= 3) {
-          const kitName = `${parts[0]}/${parts[1]}`;
-          console.log(chalk.gray(`  所属套包: ${kitName}`));
-        }
+  for (const item of installations) {
+    const icon = getTypeIcon(item.type);
+    const time = formatRelativeTime(item.installedAt);
 
-        console.log(chalk.gray(`  安装于 ${time}`));
-        console.log();
+    console.log(`${icon} ${chalk.cyan.bold(item.fullName)} ${chalk.gray(`v${item.version}`)}`);
+
+    // 解析所属套包：fullName 格式为 author/kit/plugin
+    const parts = item.fullName.split('/');
+    if (parts.length >= 3) {
+      const kitName = `${parts[0]}/${parts[1]}`;
+      console.log(chalk.gray(`  所属套包: ${kitName}`));
+    }
+
+    console.log(chalk.gray(`  安装于 ${time}`));
+    console.log();
+  }
+}
+
+async function listAllProjects(options: { type?: string; json?: boolean }): Promise<void> {
+  let installations = await getAllInstallations();
+
+  // 类型筛选
+  if (options.type) {
+    installations = installations.filter((i) => i.type === options.type);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(installations, null, 2));
+    return;
+  }
+
+  if (installations.length === 0) {
+    console.log(chalk.yellow('未安装任何插件'));
+    return;
+  }
+
+  // 按项目分组，区分全局和项目
+  const globalPlugins: typeof installations = [];
+  const byProject = new Map<string, typeof installations>();
+
+  for (const item of installations) {
+    if (isGlobalDir(item.projectPath)) {
+      globalPlugins.push(item);
+    } else {
+      const key = item.projectPath;
+      if (!byProject.has(key)) {
+        byProject.set(key, []);
       }
-    } catch (error) {
-      console.error(chalk.red((error as Error).message));
-      process.exit(1);
+      byProject.get(key)!.push(item);
     }
-  });
+  }
+
+  const projectCount = byProject.size + (globalPlugins.length > 0 ? 1 : 0);
+  console.log(chalk.gray(`共 ${installations.length} 个插件，分布在 ${projectCount} 个位置:\n`));
+
+  // 先显示全局插件
+  if (globalPlugins.length > 0) {
+    console.log(chalk.cyan.bold(`🌐 全局`) + chalk.gray(' (~/.claude/) - 对所有项目生效'));
+    for (const item of globalPlugins) {
+      const icon = getTypeIcon(item.type);
+      console.log(`   ${icon} ${chalk.cyan(item.fullName)} ${chalk.gray(`v${item.version}`)}`);
+    }
+    console.log();
+  }
+
+  // 再显示各项目
+  for (const [projectPath, items] of byProject) {
+    console.log(chalk.bold(`📁 ${projectPath}`));
+
+    for (const item of items) {
+      const icon = getTypeIcon(item.type);
+      console.log(`   ${icon} ${chalk.cyan(item.fullName)} ${chalk.gray(`v${item.version}`)}`);
+    }
+    console.log();
+  }
+}

package/src/commands/uninstall.ts

@@ -6,6 +6,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import ora from 'ora';
 import { api } from '../api';
+import { config } from '../config';
 import { getInstallations, removeInstallation, removeLink, removeCache } from '../db';
 import { parseTarget } from '../utils';
 import { TargetType } from '../types';
@@ -14,18 +15,24 @@ export const uninstallCommand = new Command('uninstall')
   .alias('rm')
   .description('卸载插件或套包')
   .argument('<target>', '插件名 (author/name) 或套包名 (author/kit/slug)')
-  .option('--purge', '同时清除缓存')
+  .option('-g, --global', '从全局目录卸载 (~/.claude/)')
+  .option('--purge', '同时清除下载缓存')
   .action(async (target, options) => {
     try {
       const parsed = parseTarget(target);
-      const projectPath = process.cwd();
+      const projectPath = options.global ? config.globalDir : process.cwd();
+
+      // 显示操作范围提示
+      if (options.global) {
+        console.log(chalk.gray('从全局目录卸载 (~/.claude/)\n'));
+      }
 
       if (parsed.type === TargetType.Kit) {
         // 卸载套包：批量卸载所有来自该套包的插件
-        await uninstallKit(projectPath, parsed.fullName, options.purge);
+        await uninstallKit(projectPath, parsed.fullName, options.purge, options.global);
       } else {
         // 卸载单个插件
-        await uninstallPlugin(projectPath, parsed.fullName, options.purge);
+        await uninstallPlugin(projectPath, parsed.fullName, options.purge, options.global);
       }
     } catch (error) {
       console.error(chalk.red((error as Error).message));
@@ -39,7 +46,8 @@ export const uninstallCommand = new Command('uninstall')
 async function uninstallPlugin(
   projectPath: string,
   fullName: string,
-  purge: boolean
+  purge: boolean,
+  isGlobal: boolean
 ): Promise<void> {
   const spinner = ora(`卸载 ${fullName}...`).start();
 
@@ -49,6 +57,11 @@ async function uninstallPlugin(
 
   if (!installation) {
     spinner.fail(`未找到已安装的插件: ${fullName}`);
+    if (isGlobal) {
+      console.log(chalk.gray('提示: 该插件可能安装在某个项目目录下，请进入项目目录后重试'));
+    } else {
+      console.log(chalk.gray('提示: 使用 42plugin uninstall --global 从全局目录卸载'));
+    }
     process.exit(1);
   }
 
@@ -78,6 +91,11 @@ async function uninstallPlugin(
   } else {
     spinner.succeed(`已卸载 ${fullName}`);
   }
+
+  // 显示位置提示
+  if (isGlobal) {
+    console.log(chalk.gray('  已从全局目录移除'));
+  }
 }
 
 /**
@@ -86,7 +104,8 @@ async function uninstallPlugin(
 async function uninstallKit(
   projectPath: string,
   kitFullName: string,
-  purge: boolean
+  purge: boolean,
+  isGlobal: boolean
 ): Promise<void> {
   const spinner = ora(`查找套包 ${kitFullName} 的插件...`).start();
 
@@ -96,6 +115,11 @@ async function uninstallKit(
 
   if (kitInstallations.length === 0) {
     spinner.fail(`未找到来自套包 ${kitFullName} 的已安装插件`);
+    if (isGlobal) {
+      console.log(chalk.gray('提示: 该套包可能安装在某个项目目录下，请进入项目目录后重试'));
+    } else {
+      console.log(chalk.gray('提示: 使用 42plugin uninstall --global 从全局目录卸载'));
+    }
     process.exit(1);
   }
 
@@ -140,6 +164,9 @@ async function uninstallKit(
     if (purge) {
       console.log(chalk.gray('  缓存已清除'));
     }
+    if (isGlobal) {
+      console.log(chalk.gray('  已从全局目录移除'));
+    }
   } else {
     console.log(chalk.yellow(`⚠ 部分卸载完成`));
     console.log(chalk.gray(`  成功: ${successCount}, 失败: ${failCount}`));

package/src/config.ts

@@ -12,13 +12,54 @@ const dataDir =
     ? path.join(process.env.APPDATA || os.homedir(), '42plugin')
     : path.join(os.homedir(), '.42plugin'));
 
+/**
+ * 平台配置 - 支持多种 AI 编程助手
+ * 未来可扩展支持 Codex、Gemini 等
+ */
+export interface PlatformConfig {
+  id: string;
+  name: string;
+  globalDir: string; // 全局安装目录（用户级）
+  projectDir: string; // 项目安装目录名
+}
+
+const homeDir = os.homedir();
+
+export const platforms: Record<string, PlatformConfig> = {
+  claude: {
+    id: 'claude',
+    name: 'Claude Code',
+    globalDir: path.join(homeDir, '.claude'),
+    projectDir: '.claude',
+  },
+  // 预留：未来扩展
+  // codex: {
+  //   id: 'codex',
+  //   name: 'OpenAI Codex CLI',
+  //   globalDir: path.join(homeDir, '.codex'),
+  //   projectDir: '.codex',
+  // },
+  // gemini: {
+  //   id: 'gemini',
+  //   name: 'Google Gemini',
+  //   globalDir: path.join(homeDir, '.gemini'),
+  //   projectDir: '.gemini',
+  // },
+};
+
+// 当前默认平台
+export const currentPlatform: PlatformConfig = platforms.claude;
+
 export const config = {
   // 目录
   dataDir,
   cacheDir: path.join(dataDir, 'cache'),
-  globalDir: path.join(dataDir, 'global'),
+  globalDir: currentPlatform.globalDir, // 全局安装目录：~/.claude
   dbPath: path.join(dataDir, 'local.db'),
 
+  // 平台
+  platform: currentPlatform,
+
   // API
   apiBaseUrl: process.env.API_BASE_URL || 'https://api.42plugin.com',
   webBaseUrl: process.env.WEB_BASE_URL || 'https://42plugin.com',
@@ -34,3 +75,22 @@ export const config = {
 export const getDataDir = () => config.dataDir;
 export const getCacheDir = () => config.cacheDir;
 export const getDbPath = () => config.dbPath;
+
+/**
+ * 获取全局目录路径
+ * @param platformId 平台 ID（默认当前平台）
+ */
+export const getGlobalDir = (platformId?: string): string => {
+  if (platformId && platforms[platformId]) {
+    return platforms[platformId].globalDir;
+  }
+  return config.globalDir;
+};
+
+/**
+ * 判断路径是否为全局目录
+ */
+export const isGlobalDir = (dirPath: string): boolean => {
+  const resolved = path.resolve(dirPath);
+  return Object.values(platforms).some((p) => path.resolve(p.globalDir) === resolved);
+};

package/src/db.ts

@@ -367,6 +367,37 @@ export async function getInstallations(projectPath: string): Promise<LocalInstal
   }));
 }
 
+export interface InstallationWithProject extends LocalInstallation {
+  projectPath: string;
+  projectName: string;
+}
+
+export async function getAllInstallations(): Promise<InstallationWithProject[]> {
+  const client = await getDb();
+
+  const rows = client.prepare(`
+    SELECT i.*, p.path as project_path, p.name as project_name
+    FROM installations i
+    JOIN projects p ON i.project_id = p.id
+    ORDER BY p.path, i.installed_at DESC
+  `).all() as Record<string, unknown>[];
+
+  return rows.map((row) => ({
+    id: row.id as string,
+    projectId: row.project_id as string,
+    fullName: row.full_name as string,
+    type: row.type as PluginType,
+    version: row.version as string,
+    cachePath: row.cache_path as string,
+    linkPath: row.link_path as string,
+    source: row.source as 'direct' | 'kit',
+    sourceKit: row.source_kit as string | undefined,
+    installedAt: row.installed_at as string,
+    projectPath: row.project_path as string,
+    projectName: row.project_name as string,
+  }));
+}
+
 export async function removeInstallation(projectPath: string, fullName: string): Promise<boolean> {
   const client = await getDb();
   const absPath = path.resolve(projectPath);

package/src/services/publisher.ts

@@ -9,6 +9,8 @@
  * 5. 确认发布
  */
 
+import fs from 'fs/promises';
+import path from 'path';
 import ora from 'ora';
 import chalk from 'chalk';
 import { confirm } from '@inquirer/prompts';
@@ -24,6 +26,7 @@ import type {
   PublishResult,
   PackageResult,
   ValidationResult,
+  PluginType,
 } from '../types';
 
 export class Publisher {
@@ -143,6 +146,9 @@ export class Publisher {
       const uploadResult = await this.uploader.upload(metadata, pkg, versionDecision.version);
       spinner.succeed('上传完成');
 
+      // 读取文档内容
+      const docContent = await this.readDocContent(metadata.sourcePath, metadata.type);
+
       // Phase 5: 确认发布
       spinner.start('确认发布...');
       const result = await api.confirmPublish({
@@ -157,6 +163,7 @@ export class Publisher {
         description: metadata.description,
         tags: metadata.tags,
         visibility: options.visibility || 'self',
+        docContent,
       });
       spinner.succeed('发布成功');
 
@@ -234,4 +241,82 @@ export class Publisher {
     const session = await api.getSession();
     return session.user.username || session.user.name || 'unknown';
   }
+
+  /**
+   * 读取插件文档内容
+   * 优先级：类型对应文档 > README.md > 任意 .md 文件
+   */
+  private async readDocContent(sourcePath: string, pluginType: PluginType): Promise<string | undefined> {
+    const MAX_DOC_SIZE = 100 * 1024; // 100KB 限制（与 Pipeline 一致）
+
+    const stat = await fs.stat(sourcePath).catch(() => null);
+
+    // 单文件插件：文件本身就是文档
+    if (stat?.isFile() && sourcePath.endsWith('.md')) {
+      const content = await fs.readFile(sourcePath, 'utf-8');
+      if (content.length > MAX_DOC_SIZE) {
+        return content.slice(0, MAX_DOC_SIZE);
+      }
+      return content;
+    }
+
+    if (!stat?.isDirectory()) return undefined;
+
+    // 根据类型定义优先查找的文档名
+    const typeDocNames: Record<PluginType, string[]> = {
+      skill: ['SKILL.md', 'skill.md'],
+      agent: ['AGENT.md', 'agent.md'],
+      command: ['COMMAND.md', 'command.md'],
+      hook: ['HOOK.md', 'hook.md'],
+      mcp: ['MCP.md', 'mcp.md'],
+    };
+
+    const fallbackNames = ['README.md', 'readme.md'];
+
+    // 1. 优先匹配类型对应的文档
+    const primaryDocs = typeDocNames[pluginType] || [];
+    for (const name of primaryDocs) {
+      const filePath = path.join(sourcePath, name);
+      try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        if (content.length > MAX_DOC_SIZE) {
+          return content.slice(0, MAX_DOC_SIZE);
+        }
+        return content;
+      } catch {
+        // 继续尝试下一个
+      }
+    }
+
+    // 2. Fallback 到 README
+    for (const name of fallbackNames) {
+      const filePath = path.join(sourcePath, name);
+      try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        if (content.length > MAX_DOC_SIZE) {
+          return content.slice(0, MAX_DOC_SIZE);
+        }
+        return content;
+      } catch {
+        // 继续尝试下一个
+      }
+    }
+
+    // 3. 任意 .md 文件（最后手段）
+    try {
+      const entries = await fs.readdir(sourcePath, { withFileTypes: true });
+      const mdFile = entries.find(e => e.isFile() && e.name.endsWith('.md'));
+      if (mdFile) {
+        const content = await fs.readFile(path.join(sourcePath, mdFile.name), 'utf-8');
+        if (content.length > MAX_DOC_SIZE) {
+          return content.slice(0, MAX_DOC_SIZE);
+        }
+        return content;
+      }
+    } catch {
+      // 忽略错误
+    }
+
+    return undefined;
+  }
 }

package/src/types.ts

@@ -340,6 +340,7 @@ export interface PublishConfirmRequest {
   description?: string;
   tags?: string[];
   visibility: 'self' | 'public';
+  docContent?: string;
 }
 
 export interface PublishConfirmResponse {

package/src/update-checker.ts

@@ -0,0 +1,343 @@
+/**
+ * 版本更新检查模块
+ *
+ * 功能：
+ * - 启动时后台检查 npm registry 获取最新版本
+ * - 24 小时内只检查一次，每天最多提示一次
+ * - 3 秒超时，静默失败不影响正常使用
+ * - 检测安装方式（Homebrew/npm）显示对应升级命令
+ * - 支持 NO_UPDATE_CHECK=1 环境变量禁用
+ */
+
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { config } from './config';
+
+// ============================================================================
+// 配置
+// ============================================================================
+
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 小时
+const NOTIFY_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 小时内只提示一次
+const FETCH_TIMEOUT_MS = 3000; // 3 秒超时
+const CACHE_FILE = path.join(config.dataDir, '.update-check');
+const NPM_REGISTRY_URL = 'https://registry.npmjs.org/@42ailab/42plugin/latest';
+
+// ============================================================================
+// 类型
+// ============================================================================
+
+interface UpdateCache {
+  lastCheck: number; // 上次检查时间戳
+  latestVersion: string | null; // 最新版本
+  lastNotified: number; // 上次提示时间戳
+}
+
+type InstallSource = 'homebrew' | 'npm';
+
+const DEFAULT_CACHE: UpdateCache = { lastCheck: 0, latestVersion: null, lastNotified: 0 };
+
+// ============================================================================
+// 缓存管理
+// ============================================================================
+
+function readCache(): UpdateCache {
+  try {
+    if (fs.existsSync(CACHE_FILE)) {
+      const content = fs.readFileSync(CACHE_FILE, 'utf-8');
+      const parsed = JSON.parse(content);
+      // 基本校验：确保必需字段存在
+      if (
+        typeof parsed.lastCheck === 'number' &&
+        typeof parsed.lastNotified === 'number'
+      ) {
+        return {
+          lastCheck: parsed.lastCheck,
+          latestVersion: parsed.latestVersion ?? null,
+          lastNotified: parsed.lastNotified,
+        };
+      }
+    }
+  } catch {
+    // 缓存读取/解析失败，返回默认值
+    // 可选：在 debug 模式下记录警告
+    if (config.debug) {
+      console.error(chalk.gray('[update-checker] 缓存读取失败，使用默认值'));
+    }
+  }
+  return { ...DEFAULT_CACHE };
+}
+
+function writeCache(cache: UpdateCache): void {
+  try {
+    fs.mkdirSync(path.dirname(CACHE_FILE), { recursive: true });
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(cache));
+  } catch {
+    // 缓存写入失败，忽略
+  }
+}
+
+// ============================================================================
+// 版本比较
+// ============================================================================
+
+/**
+ * 解析版本号，处理预发布版本
+ * 例如：'1.2.3-beta.1' -> { parts: [1, 2, 3], prerelease: 'beta.1' }
+ */
+function parseVersion(v: string): { parts: number[]; prerelease: string | null } {
+  const cleaned = v.replace(/^v/, '');
+  const [main, prerelease] = cleaned.split('-', 2);
+  const parts = main.split('.').map((part) => {
+    const num = parseInt(part, 10);
+    return isNaN(num) ? 0 : num;
+  });
+  return { parts, prerelease: prerelease || null };
+}
+
+/**
+ * 比较两个版本号
+ * @returns -1 表示 a < b, 0 表示 a = b, 1 表示 a > b
+ *
+ * 规则：
+ * - 主版本号按数字比较
+ * - 预发布版本 < 正式版本 (1.0.0-beta < 1.0.0)
+ * - 预发布版本之间按字符串比较
+ */
+function compareVersions(a: string, b: string): number {
+  const va = parseVersion(a);
+  const vb = parseVersion(b);
+
+  // 比较主版本号（动态长度）
+  const maxLen = Math.max(va.parts.length, vb.parts.length);
+  for (let i = 0; i < maxLen; i++) {
+    const na = va.parts[i] || 0;
+    const nb = vb.parts[i] || 0;
+    if (na < nb) return -1;
+    if (na > nb) return 1;
+  }
+
+  // 主版本号相同，比较预发布标识
+  // 有预发布标识 < 无预发布标识
+  if (va.prerelease && !vb.prerelease) return -1;
+  if (!va.prerelease && vb.prerelease) return 1;
+
+  // 都有预发布标识，按字符串比较
+  if (va.prerelease && vb.prerelease) {
+    return va.prerelease.localeCompare(vb.prerelease);
+  }
+
+  return 0;
+}
+
+// ============================================================================
+// 安装方式检测
+// ============================================================================
+
+/**
+ * 检测 CLI 的安装来源
+ */
+function detectInstallSource(): InstallSource {
+  const execPath = process.execPath;
+
+  // Homebrew 路径特征
+  // macOS ARM: /opt/homebrew/...
+  // macOS Intel: /usr/local/Cellar/...
+  // Linux: /home/linuxbrew/.linuxbrew/...
+  if (
+    execPath.includes('/opt/homebrew') ||
+    execPath.includes('/usr/local/Cellar') ||
+    execPath.includes('/linuxbrew')
+  ) {
+    return 'homebrew';
+  }
+
+  return 'npm';
+}
+
+/**
+ * 获取升级命令
+ */
+function getUpgradeCommand(source: InstallSource): string {
+  switch (source) {
+    case 'homebrew':
+      return 'brew upgrade 42plugin';
+    case 'npm':
+    default:
+      // 使用 bun，性能更好
+      return 'bun update -g @42ailab/42plugin';
+  }
+}
+
+// ============================================================================
+// 网络请求
+// ============================================================================
+
+/**
+ * 从 npm registry 获取最新版本
+ */
+async function fetchLatestVersion(): Promise<string | null> {
+  try {
+    const response = await fetch(NPM_REGISTRY_URL, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      headers: {
+        Accept: 'application/json',
+      },
+    });
+
+    if (response.ok) {
+      const data = (await response.json()) as { version?: string };
+      return data.version || null;
+    }
+  } catch {
+    // 网络错误、超时等，静默失败
+  }
+  return null;
+}
+
+// ============================================================================
+// 提示显示
+// ============================================================================
+
+/**
+ * 显示更新提示（简洁单行）
+ */
+function showUpdateNotice(currentVersion: string, latestVersion: string): void {
+  const source = detectInstallSource();
+  const command = getUpgradeCommand(source);
+
+  console.log();
+  console.log(
+    chalk.yellow(`✨ 新版本 ${latestVersion} 可用`) +
+      chalk.gray(` (当前 ${currentVersion})  `) +
+      chalk.cyan(`升级: ${command}`)
+  );
+}
+
+/**
+ * 判断是否需要显示提示并显示
+ * @returns 是否显示了提示
+ */
+function maybeShowNotice(
+  currentVersion: string,
+  latestVersion: string,
+  lastNotified: number,
+  now: number
+): boolean {
+  if (compareVersions(currentVersion, latestVersion) < 0) {
+    const needsNotify = now - lastNotified >= NOTIFY_INTERVAL_MS;
+    if (needsNotify) {
+      showUpdateNotice(currentVersion, latestVersion);
+      return true;
+    }
+  }
+  return false;
+}
+
+// ============================================================================
+// 主入口
+// ============================================================================
+
+/**
+ * 检查更新（非阻塞）
+ *
+ * 在命令执行后调用，后台检查并在需要时显示提示
+ *
+ * @param currentVersion 当前版本号
+ */
+export function checkForUpdates(currentVersion: string): void {
+  // 1. 检查是否禁用
+  if (process.env.NO_UPDATE_CHECK === '1') {
+    return;
+  }
+
+  // 2. 读取缓存
+  const cache = readCache();
+  const now = Date.now();
+
+  // 3. 判断是否需要检查
+  const needsCheck = now - cache.lastCheck >= CHECK_INTERVAL_MS;
+
+  if (needsCheck) {
+    // 后台检查，使用立即执行的异步函数
+    // 注意：这里不使用 setImmediate，因为 CLI 可能在回调执行前退出
+    // 改用 Promise，让 Node.js 事件循环保持活跃直到完成
+    (async () => {
+      try {
+        const latestVersion = await fetchLatestVersion();
+
+        // 重新读取缓存以避免竞态条件
+        const freshCache = readCache();
+        const freshNow = Date.now();
+
+        // 更新缓存
+        const newCache: UpdateCache = {
+          lastCheck: freshNow,
+          latestVersion: latestVersion ?? freshCache.latestVersion,
+          lastNotified: freshCache.lastNotified,
+        };
+
+        // 判断是否需要提示
+        if (latestVersion) {
+          const didNotify = maybeShowNotice(
+            currentVersion,
+            latestVersion,
+            freshCache.lastNotified,
+            freshNow
+          );
+          if (didNotify) {
+            newCache.lastNotified = freshNow;
+          }
+        }
+
+        writeCache(newCache);
+      } catch {
+        // 静默失败
+      }
+    })();
+  } else {
+    // 使用缓存的版本信息判断
+    if (cache.latestVersion) {
+      const didNotify = maybeShowNotice(
+        currentVersion,
+        cache.latestVersion,
+        cache.lastNotified,
+        now
+      );
+      if (didNotify) {
+        writeCache({ ...cache, lastNotified: now });
+      }
+    }
+  }
+}
+
+/**
+ * 主动检查更新（阻塞，用于 version --check）
+ *
+ * @param currentVersion 当前版本号
+ * @returns 是否有新版本
+ */
+export async function checkForUpdatesSync(currentVersion: string): Promise<boolean> {
+  const latestVersion = await fetchLatestVersion();
+
+  if (!latestVersion) {
+    console.log(chalk.gray('无法获取最新版本信息'));
+    return false;
+  }
+
+  // 更新缓存
+  writeCache({
+    lastCheck: Date.now(),
+    latestVersion,
+    lastNotified: Date.now(),
+  });
+
+  if (compareVersions(currentVersion, latestVersion) < 0) {
+    showUpdateNotice(currentVersion, latestVersion);
+    return true;
+  } else {
+    console.log(chalk.green('✓ 已是最新版本'));
+    return false;
+  }
+}