feat(plugin): add update command, hot reload after install, README section (#307)

- Add `opencli plugin update <name>` command (git pull + post-install lifecycle)
- Extract shared postInstallLifecycle() helper to deduplicate install/update code
- Hot reload: call discoverPlugins() after install/update (no restart needed)
- Add Plugins section to README.md and README.zh-CN.md
- Add updatePlugin test coverage

Author: jackwener

README.md

@@ -262,6 +262,25 @@ opencli bilibili hot -f csv     # CSV
 opencli bilibili hot -v         # Verbose: show pipeline debug steps
 ```
 
+## Plugins
+
+Extend OpenCLI with community-contributed adapters. Plugins use the same YAML/TS format as built-in commands and are automatically discovered at startup.
+
+```bash
+opencli plugin install github:user/opencli-plugin-my-tool  # Install
+opencli plugin list                                         # List installed
+opencli plugin update my-tool                               # Update to latest
+opencli plugin uninstall my-tool                            # Remove
+```
+
+| Plugin | Type | Description |
+|--------|------|-------------|
+| [opencli-plugin-github-trending](https://github.com/ByteYue/opencli-plugin-github-trending) | YAML | GitHub Trending repositories |
+| [opencli-plugin-hot-digest](https://github.com/ByteYue/opencli-plugin-hot-digest) | TS | Multi-platform trending aggregator |
+| [opencli-plugin-juejin](https://github.com/Astro-Han/opencli-plugin-juejin) | YAML | 稀土掘金 (Juejin) hot articles |
+
+See [Plugins Guide](./docs/guide/plugins.md) for creating your own plugin.
+
 ## For AI Agents (Developer Guide)
 
 If you are an AI assistant tasked with creating a new command adapter for `opencli`, please follow the AI Agent workflow below:

README.zh-CN.md

@@ -264,6 +264,25 @@ opencli bilibili hot -f csv     # CSV
 opencli bilibili hot -v         # 详细模式：展示管线执行步骤调试信息
 ```
 
+## 插件
+
+通过社区贡献的插件扩展 OpenCLI。插件使用与内置命令相同的 YAML/TS 格式，启动时自动发现。
+
+```bash
+opencli plugin install github:user/opencli-plugin-my-tool  # 安装
+opencli plugin list                                         # 查看已安装
+opencli plugin update my-tool                               # 更新到最新
+opencli plugin uninstall my-tool                            # 卸载
+```
+
+| 插件 | 类型 | 描述 |
+|------|------|------|
+| [opencli-plugin-github-trending](https://github.com/ByteYue/opencli-plugin-github-trending) | YAML | GitHub Trending 仓库 |
+| [opencli-plugin-hot-digest](https://github.com/ByteYue/opencli-plugin-hot-digest) | TS | 多平台热榜聚合 |
+| [opencli-plugin-juejin](https://github.com/Astro-Han/opencli-plugin-juejin) | YAML | 稀土掘金热门文章 |
+
+详见 [插件指南](./docs/zh/guide/plugins.md) 了解如何创建自己的插件。
+
 ## 致 AI Agent（开发者指南）
 
 如果你是一个被要求查阅代码并编写新 `opencli` 适配器的 AI，请遵守以下工作流。

src/cli.ts

@@ -257,10 +257,11 @@ export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
     .argument('<source>', 'Plugin source (e.g. github:user/repo)')
     .action(async (source: string) => {
       const { installPlugin } = await import('./plugin.js');
+      const { discoverPlugins } = await import('./discovery.js');
       try {
         const name = installPlugin(source);
-        console.log(chalk.green(`✅ Plugin "${name}" installed successfully.`));
-        console.log(chalk.dim(`   Restart opencli to use the new commands.`));
+        await discoverPlugins();
+        console.log(chalk.green(`✅ Plugin "${name}" installed successfully. Commands are ready to use.`));
       } catch (err: any) {
         console.error(chalk.red(`Error: ${err.message}`));
         process.exitCode = 1;
@@ -282,6 +283,24 @@ export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
       }
     });
 
+  pluginCmd
+    .command('update')
+    .description('Update a plugin to the latest version')
+    .argument('<name>', 'Plugin name')
+    .action(async (name: string) => {
+      const { updatePlugin } = await import('./plugin.js');
+      const { discoverPlugins } = await import('./discovery.js');
+      try {
+        updatePlugin(name);
+        await discoverPlugins();
+        console.log(chalk.green(`✅ Plugin "${name}" updated successfully.`));
+      } catch (err: any) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+
   pluginCmd
     .command('list')
     .description('List installed plugins')

src/plugin.test.ts

@@ -6,7 +6,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { PLUGINS_DIR } from './discovery.js';
-import { listPlugins, uninstallPlugin, _parseSource } from './plugin.js';
+import { listPlugins, uninstallPlugin, updatePlugin, _parseSource } from './plugin.js';
 
 describe('parseSource', () => {
   it('parses github:user/repo format', () => {
@@ -84,3 +84,9 @@ describe('uninstallPlugin', () => {
     expect(() => uninstallPlugin('__nonexistent__')).toThrow('not installed');
   });
 });
+
+describe('updatePlugin', () => {
+  it('throws for non-existent plugin', () => {
+    expect(() => updatePlugin('__nonexistent__')).toThrow('not installed');
+  });
+});

src/plugin.ts

@@ -18,6 +18,32 @@ export interface PluginInfo {
   source?: string;
 }
 
+/**
+ * Shared post-install lifecycle: npm install → host symlink → TS transpile.
+ * Called by both installPlugin() and updatePlugin().
+ */
+function postInstallLifecycle(pluginDir: string): void {
+  const pkgJsonPath = path.join(pluginDir, 'package.json');
+  if (!fs.existsSync(pkgJsonPath)) return;
+
+  try {
+    execFileSync('npm', ['install', '--omit=dev'], {
+      cwd: pluginDir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch {
+    // Non-fatal: npm install may fail if no real deps
+  }
+
+  // Symlink host opencli so TS plugins resolve '@jackwener/opencli/registry'
+  // against the running host, not a stale npm-published version.
+  linkHostOpencli(pluginDir);
+
+  // Transpile .ts → .js via esbuild (production node can't load .ts directly).
+  transpilePluginTs(pluginDir);
+}
+
 /**
  * Install a plugin from a source.
  * Currently supports "github:user/repo" format (git clone wrapper).
@@ -52,31 +78,7 @@ export function installPlugin(source: string): string {
     throw new Error(`Failed to clone plugin: ${err.message}`);
   }
 
-  // If the plugin has a package.json, run npm install for regular deps,
-  // then symlink the host opencli into node_modules for peerDep resolution.
-  const pkgJsonPath = path.join(targetDir, 'package.json');
-  if (fs.existsSync(pkgJsonPath)) {
-    try {
-      execFileSync('npm', ['install', '--omit=dev'], {
-        cwd: targetDir,
-        encoding: 'utf-8',
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
-    } catch {
-      // Non-fatal: npm install may fail if no real deps
-    }
-
-    // Symlink host opencli into plugin's node_modules so TS plugins
-    // can resolve '@jackwener/opencli/registry' against the running host.
-    // This is more reliable than depending on the npm-published version
-    // which may lag behind the local installation.
-    linkHostOpencli(targetDir);
-
-    // Transpile TS plugin files to JS so they work in production mode
-    // (node cannot load .ts files directly without tsx).
-    transpilePluginTs(targetDir);
-  }
-
+  postInstallLifecycle(targetDir);
   return name;
 }
 
@@ -91,6 +93,28 @@ export function uninstallPlugin(name: string): void {
   fs.rmSync(targetDir, { recursive: true, force: true });
 }
 
+/**
+ * Update a plugin by name (git pull + re-install lifecycle).
+ */
+export function updatePlugin(name: string): void {
+  const targetDir = path.join(PLUGINS_DIR, name);
+  if (!fs.existsSync(targetDir)) {
+    throw new Error(`Plugin "${name}" is not installed.`);
+  }
+
+  try {
+    execFileSync('git', ['pull', '--ff-only'], {
+      cwd: targetDir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch (err: any) {
+    throw new Error(`Failed to update plugin: ${err.message}`);
+  }
+
+  postInstallLifecycle(targetDir);
+}
+
 /**
  * List all installed plugins.
  */