可扩展性分析¶

重要性：⭐⭐⭐⭐（扩展全景——10+ 种扩展方式）范围：src/ 全部扩展点方法：grep 扩展相关代码 + 分类

1. 10 大扩展方式¶

┌──────────────────────────────────────────┐
│  1. Plugins（最强）                       │
│  2. MCP servers                          │
│  3. Hooks                                │
│  4. Skills                               │
│  5. Custom Agents                        │
│  6. Slash Commands                       │
│  7. Keybindings                          │
│  8. Output Styles                        │
│  9. Marketplace                          │
│  10. Settings (settings.json)            │
└──────────────────────────────────────────┘

10 大扩展 —— 从强到弱。

2. Plugins（最强扩展）¶

详见 topics/deep-dive-plugin-loader.md。

能做什么： - 注册 hook - 注册 command - 注册 agent - 注册 MCP server - 提供 settings - 提供 UI 资源

安装源（6 种）： - npm - git - GitHub - git-subdir (monorepo) - local - session-only (--plugin-dir)

配置文件：plugin.json manifest。

加载：pluginLoader.ts 6 种源 + 4 级缓存。

3. MCP Servers¶

详见 topics/deep-dive-mcp-client.md。

能做什么： - 注册 tool - 注册 resource - 注册 command - 自定义 transport

4 种 transport： - stdio - SSE - Streamable HTTP - WebSocket

配置位置： - ~/.claude.json (user) - .mcp.json (project) - --mcp-config (CLI)

鉴权： - OAuth 2.0 + PKCE - API key

4. Hooks¶

9 种 hook 事件（推测）： - PreToolUse - PostToolUse - SessionStart - SessionEnd - Notification - Stop - SubagentStop - UserPromptSubmit - PreCompact

配置位置：settings.json 的 hooks 字段。

Hook 类型： - command（执行 shell） - prompt（LLM 评估） - agent（agent 循环）

示例：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/bin/check-bash.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

5. Skills¶

详见 topics/deep-dive-marketplace.md (相关)。

能做什么： - 触发 /skill-name 命令 - 注入 prompt - 执行代码

配置位置： - ~/.claude/skills/ - .claude/skills/

SKILL.md 格式（推测）：

---
name: my-skill
description: ...
---
# My Skill
... instructions ...

加载：skillSearch/prefetch.ts + getSkillListingAttachments。

6. Custom Agents¶

详见 topics/deep-dive-agent-tool.md (现有)。

能做什么： - 自定义 system prompt - 工具子集 - 模型选择 - 颜色 / 名称

配置位置： - .claude/agents/<name>.md - --agents '{"name": {...}}'

Markdown 格式：

---
name: my-agent
description: ...
tools: Bash, Read
model: sonnet
---
You are a specialized agent...

7. Slash Commands¶

103 个 subcommand（推测）。

自定义方式： - .claude/commands/<name>.md - 通过 plugins - 内置 commands

Markdown 格式：

---
description: My custom command
---
Process the following: $ARGUMENTS

$ARGUMENTS 替换为用户输入。

8. Keybindings¶

详见 topics/keybindings-help.md (A3 待做) 与 keybindings/ 目录。

配置位置： - 内置（keybindings/） - 用户 settings - plugins

格式：

{
  "keybindings": [
    { "key": "ctrl+k", "command": "clear" }
  ]
}

支持操作（推测）： - 单键 - 组合键 (Ctrl+X) - 双击 (Esc Esc) - 序列 (g g) - 模式 (normal/insert)

9. Output Styles¶

配置位置：.claude/outputStyles/ 或 settings。

能做什么： - 改变输出格式 - markdown / html - 不同的 default behavior

推测：

---
name: explanatory
description: Detailed explanations
---
# Detailed Explanations
...

10. Marketplace¶

详见 topics/deep-dive-marketplace.md (现有)。

能做什么： - 集中分发 plugin - 私有 marketplace - 官方 seed marketplace

配置位置： - 用户 settings (marketplaces) - 项目 settings

Marketplace 源： - git URL - HTTPS URL - local path - seed (内置)

11. Settings (settings.json)¶

最强 meta-扩展 —— 配置一切。

配置层级（从高到低）： 1. policySettings (enterprise, MD-managed) 2. localSettings (项目 local) 3. projectSettings (项目) 4. userSettings (用户)

能配置： - 模型 - 工具白/黑名单 - Hooks - MCP servers - Plugins - Marketplace - Keybindings - Output styles - Permissions - 等等

示例：

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Bash(git:*)"],
    "deny": ["Bash(rm -rf:*)"]
  },
  "hooks": { ... },
  "mcpServers": { ... },
  "plugins": { ... }
}

12. 扩展点 vs 实现¶

扩展点	实现位置	注册方式
Plugins	`utils/plugins/`	`plugin.json`
MCP servers	`services/mcp/`	`~/.claude.json`
Hooks	`utils/hooks.ts` (5022 行)	`settings.json`
Skills	`services/skills/`	SKILL.md
Agents	`tools/AgentTool/`	`<name>.md`
Commands	`commands/`	`<name>.md`
Keybindings	`keybindings/`	`settings.json`
Output Styles	`outputStyles/`	settings
Marketplace	`utils/plugins/marketplaceManager.ts`	`settings.json`
Settings	多源	4 级

13. 扩展的"层级"¶

                    ┌─────────────┐
                    │  Plugins    │  ← 第三方分发
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
         ┌────▼────┐  ┌────▼────┐  ┌────▼────┐
         │  MCP    │  │  Hooks  │  │ Skills  │  ← 行为
         └────┬────┘  └────┬────┘  └────┬────┘
              │            │            │
              └────────────┼────────────┘
                           │
                    ┌──────▼──────┐
                    │  Settings   │  ← 配置
                    └─────────────┘

层级关系 —— Settings 是底层，Plugins 是顶层。

14. 扩展的"安全模型"¶

扩展	沙箱	信任模型
Plugins	无	完全信任（需审查）
MCP servers	无	完全信任（需审查）
Hooks	无	完全信任
Skills	无	完全信任
Agents	无	完全信任
Commands	无	完全信任
Settings	N/A	N/A（meta）

所有扩展都跑在主进程 —— 零隔离。

已知风险 —— 详见 security-audit.md。

15. 扩展点的"完整度"¶

扩展	完整度	备注
Plugins	⭐⭐⭐⭐⭐	6 源 + 4 级 cache + marketplace
MCP	⭐⭐⭐⭐⭐	4 transport + OAuth + reconnect
Hooks	⭐⭐⭐⭐	9 事件 + 3 类型
Skills	⭐⭐⭐	触发 + prompt 注入
Agents	⭐⭐⭐⭐	系统提示 + 工具子集
Commands	⭐⭐⭐⭐	103 subcommand
Keybindings	⭐⭐⭐	双击 / 序列 / 模式
Output Styles	⭐⭐	简单 YAML
Marketplace	⭐⭐⭐⭐	Git/HTTPS/local/seed
Settings	⭐⭐⭐⭐⭐	4 级 + enterprise

16. "扩展友好" 设计¶

16.1 feature('X') 编译时门控¶

新功能不影响老用户。

16.2 lazy require 循环解¶

新模块不破坏老模块。

16.3 memoize 缓存¶

新调用不重复计算。

16.4 hooks 抽象¶

9 种事件统一接口。

16.5 settings 多源¶

4 级合并 —— 灵活。

17. "扩展困难" 设计¶

17.1 hooks 全权¶

没有 sandbox —— 高风险。

17.2 Plugin 无进程隔离¶

主进程跑 —— 崩溃 = CLI 崩。

17.3 输出格式不开放¶

仅 markdown / html —— 第三方难扩展。

17.4 Keybindings 不易发现¶

配置复杂 —— UX 待改进。

17.5 没有"plugin store"¶

用户必须自己找 —— 无中心化。

18. 关键洞察¶

18.1 10 大扩展方式¶

完整生态 —— 从弱到强全覆盖。

18.2 零隔离¶

所有扩展在主进程 —— 性能 + 简单，但安全风险。

18.3 Settings 是"底层扩展"¶

所有扩展最终通过 settings 配置。

18.4 Plugins 是"顶层"¶

分发 + 安装 + 沙箱（无）。

18.5 MCP 是"互联标准"¶

跨厂商协议 —— 生态扩展。

18.6 Hooks 是"行为注入"¶

9 事件 统一接口。

18.7 Skills 是"提示工程"¶

SKILL.md 注入。

18.8 Agents 是"角色化"¶

system prompt + 工具子集。

18.9 Marketplace 是"分发"¶

git 生态。

18.10 信任模型是"零"¶

所有扩展需审查。

19. 改进方向¶

19.1 Plugin 沙箱¶

process isolation / Worker thread。

19.2 Hook 沙箱¶

限制可访问 API。

19.3 中心化 plugin store¶

类似 npm 的"plugin market"。

19.4 输出格式扩展¶

插件化输出格式。

19.5 Keybindings UX 改进¶

可视化配置 UI。

20. 阅读建议¶

看 utils/plugins/pluginLoader.ts —— Plugins
看 services/mcp/client.ts —— MCP
看 utils/hooks.ts —— Hooks
看 tools/AgentTool/ —— Agents
看 commands/ —— Commands

21. 与其他分析的关系¶

文件	关系
`security-audit.md`	扩展的安全风险
`module-dependencies.md`	扩展的代码位置
`architecture-history.md`	扩展的演进