plugin` 插件管理 UI¶

重要性：⭐⭐⭐（/plugin 命令 UI——插件列表 / 详情 / 配置 / 启用 / 禁用 / 卸载） 真实位置：src/commands/plugin/ManagePlugins.tsx（2214 行）角色：/plugin 命令的交互式 UI——浏览、安装、启用、禁用、配置、卸载 plugin 关联：topics/deep-dive-plugin-loader.md（plugin 加载）、topics/deep-dive-marketplace.md（marketplace）

1. 文件全景¶

ManagePlugins.tsx (2214 行)
│
├── 行 1-130  ：imports + 6 个 type
│   ├── Props (行 54)
│   ├── FlaggedPluginInfo (行 63)
│   ├── FailedPluginInfo (行 71)
│   ├── ViewState (行 78, ~28 行, 4 种视图)
│   ├── MarketplaceInfo (行 106)
│   └── PluginState (行 112, ~17 行)
│
├── 行 129-195：3 个 file/dir helper
│   ├── getBaseFileNames (行 129, ~30 行)
│   ├── getSkillDirNames (行 160, ~35 行)
│   └── PluginComponentsDisplay (行 194, ~180 行) — 子组件
│
├── 行 376-395：2 个 helper
│   ├── checkIfLocalPlugin (行 376, ~15 行)
│   └── filterManagedDisabledPlugins (行 391, ~5 行)
│
└── 行 397-2214：**ManagePlugins 主组件（~1817 行）** — God Component

核心洞察：整个文件就是 1 个主组件 + 1 个子组件 + 几个 helper。

2. 4 种 ViewState（行 78）¶

type ViewState = 'plugin-list' | 'plugin-details' | 'configuring' | '...'

4+ 种视图： - plugin-list —— 列表 - plugin-details —— 详情 - configuring —— 配置 - ... 还可能有更多

3. 6 个 Type¶

type Props = { ... }                    // 组件 props
type FlaggedPluginInfo = { ... }        // 被 flag 的 plugin
type FailedPluginInfo = { ... }         // 加载失败的 plugin
type ViewState = ...                    // 视图状态
type MarketplaceInfo = { ... }          // marketplace 信息
type PluginState = { ... }              // plugin 状态

6 个 type —— UI 状态完整建模。

4. `PluginComponentsDisplay` — 180 行子组件（行 194）¶

function PluginComponentsDisplay({ ... }) {
  // 显示 plugin 的组件：commands / agents / hooks / mcpServers
}

子组件 —— 展示 plugin 提供的各类资源。

5. `getBaseFileNames` + `getSkillDirNames`（行 129, 160）¶

async function getBaseFileNames(dirPath: string): Promise<string[]> {
  // 读目录的文件名（不含扩展名）
}

async function getSkillDirNames(dirPath: string): Promise<string[]> {
  // 读 skills 目录
}

2 个 helper —— filesystem reads。

6. `checkIfLocalPlugin` — 15 行（行 376）¶

async function checkIfLocalPlugin(pluginName, marketplaceName): Promise<string | null> {
  // 检查是不是 local plugin
}

local 检查 —— --plugin-dir 安装的 plugin。

7. `filterManagedDisabledPlugins` — 5 行（行 391）¶

export function filterManagedDisabledPlugins(plugins: LoadedPlugin[]): LoadedPlugin[] {
  return plugins.filter(p => p.disabled && isManagedPlugin(p))
}

5 行 —— 过滤被 managed policy 禁用的 plugin。

8. `ManagePlugins` 主组件 — 1817 行（行 397-2214）¶

8.1 13 个 Hooks¶

useAppState, useSetAppState
useState, useEffect, useMemo, useCallback, useRef
useInput (Ink)
useKeybinding, useKeybindings
useSearchInput
useMcpToggleEnabled
useTerminalFocus, useTerminalSize

13 个 hooks —— 比 PromptInput 少，但够用。

8.2 主组件结构¶

ManagePlugins (行 397-2214, ~1817 行)
│
├── A. 初始化 (~150 行)
│   ├── props destructuring
│   ├── env-var 缓存
│   ├── 局部 state
│   └── AppState 订阅
│
├── B. 业务 hooks (~300 行)
│   ├── useSearchInput
│   ├── useMcpToggleEnabled
│   ├── useTerminalFocus
│   └── ...
│
├── C. 派生数据 (~200 行)
│   ├── filtered plugins
│   ├── grouped by marketplace
│   ├── search results
│   └── ViewState 转换
│
├── D. 事件处理 (~500 行)
│   ├── installPlugin
│   ├── enablePlugin / disablePlugin
│   ├── uninstallPlugin
│   ├── configurePlugin
│   ├── searchMarketplace
│   └── onSubmit
│
├── E. 视图 dispatch (~200 行)
│   ├── list 视图
│   ├── details 视图
│   ├── configuring 视图
│   └── confirm dialog
│
└── F. JSX render (~450 行)
    ├── Box layout
    ├── search bar
    ├── plugin list
    ├── plugin details
    └── footer

~1817 行单组件 —— God Component 模式。

8.3 4 种视图¶

plugin-list —— 列表（带搜索）
plugin-details —— 单 plugin 详情
configuring —— 配置中
确认对话框 —— 删除 / 启用 / 禁用

8.4 操作¶

Install —— 从 marketplace 安装
Enable / Disable —— 启用 / 禁用
Configure —— 改 settings
Uninstall —— 卸载
Search —— 搜 marketplace

8.5 `useSearchInput` 集成¶

复用 useSearchInput hook —— / 触发搜索。

9. 关键设计模式¶

9.1 God Component¶

1817 行单组件 —— 与 REPL.tsx / PromptInput.tsx 一致。

9.2 4 种 ViewState¶

视图状态机 —— list → details → configuring。

9.3 13 个 hooks 编排¶

业务在 hooks —— 组件只编排。

9.4 PluginState 完整建模¶

type PluginState = { ... }  // 状态：installed / enabled / disabled / failed

State machine —— plugin 生命周期完整建模。

9.5 6 个 Type 完整¶

类型驱动 —— 6 个 type 覆盖所有 UI 状态。

9.6 MarketplaceInfo + FlaggedPluginInfo¶

额外状态： - MarketplaceInfo —— marketplace 元数据 - FlaggedPluginInfo —— 被 flag 的 plugin（安全警告） - FailedPluginInfo —— 加载失败

9.7 Search 集成¶

useSearchInput —— marketplace 搜索。

9.8 MCP 切换¶

useMcpToggleEnabled —— 直接 enable/disable MCP server。

10. 复杂度分析¶

维度	数字
总行数	2214
Type	6
Helper	5
主组件	1 (1817 行)
唯一 Hooks	13
ViewState	4+
操作	5+ (install/enable/disable/configure/uninstall)

11. 与其他文件的关系¶

ManagePlugins.tsx
  ├──→ marketplaceManager.ts (install/refresh)
  ├──→ pluginLoader.ts (load/loadAllPlugins)
  ├──→ pluginCliCommands.ts (uninstall/...)
  ├──→ hooks/useSearchInput.js
  ├──→ hooks/useMcpToggleEnabled.js
  ├──→ components/PluginComponentsDisplay
  └──→ /plugin 命令入口

12. 关键洞察¶

12.1 4 种 ViewState 是状态机¶

list ↔ details ↔ configuring —— 显式状态机。

12.2 6 个 Type 完整建模¶

Type-driven —— TypeScript 类型是契约。

12.3 FlaggedPluginInfo 是"安全 UI"¶

被 flag 的 plugin —— 警告用户。

12.4 FailedPluginInfo 是"失败恢复"¶

加载失败的 plugin —— 可重试。

12.5 useMcpToggleEnabled 直接 hook¶

MCP server 启用/禁用 —— 直接 hook。

12.6 Search 复用 useSearchInput¶

不重写 —— 复用现有 hook。

12.7 PluginState 完整¶

installed / enabled / disabled / failed —— 生命周期完整。

12.8 Marketplace 集成¶

从 marketplace 安装 —— 生态完整。

13. 阅读建议¶

看 6 个 Type（行 54-130）—— 数据模型
看 ViewState（行 78）—— 4 种视图
看 PluginComponentsDisplay（行 194）—— 子组件
跳看 ManagePlugins 主组件（行 397）—— 编排
看 install/enable/disable 操作—— 用户动作

14. 与其他深度拆解的关系¶

文件	关系
`pluginLoader.ts`	加载
`marketplaceManager.ts`	marketplace
`pluginCliCommands.ts`	CLI

15. 阅读清单¶

✅ 看 6 个 Type（行 54-130）
✅ 看 ViewState（行 78）
✅ 看 PluginComponentsDisplay（行 194）
✅ 看 ManagePlugins 主组件（行 397）
📌 跑 /plugin 实际看 UI
📌 对照 topics/deep-dive-plugin-loader.md

16. 练习任务¶

数 ViewState（grep）—— 4+
数 operations（grep install/enable/disable）—— 5+
画 4 种视图状态机 —— list ↔ details ↔ configuring
手写迷你 ManagePlugins（~100 行）—— 1 个列表 + 1 个 enable 操作
思考：plugin UI 还能加什么操作？（如 update、settings edit）

Deep Dive ｜ src/commands/plugin/ManagePlugins.tsx 2214 行 — /plugin 插件管理 UI¶