Harness Marketplace 剖析系列 - 之 Claude Code：Harness 如何加载和执行 Plugin 能力

前面的文章已经完成了两层分析。

第一层是 Plugin 的静态结构：

Plugin ├── plugin.json ├── skills/ ├── commands/ ├── agents/ ├── hooks/ ├── .mcp.json └── .lsp.json

第二层是 Plugin 从 Marketplace 到本地的安装过程：

Marketplace Entry ↓ 定位 Plugin Source ↓ 复制到版本化 Cache ↓ 写入 enabledPlugins ↓ 等待 Claude Code 加载

但到这里，Plugin 仍然只是一组保存在磁盘上的文件。

真正决定 Plugin 是否有用的是下一步：

Claude Code Harness 如何把这些文件转化成模型可理解、可选择、可调用的运行时能力？

例如，一个放在：

skills/code-review/SKILL.md

中的 Markdown 文件，为什么会出现在 Claude 的可用 Skill 列表中？

一个位于：

agents/security-reviewer.md

中的 Agent 定义，又是如何获得独立上下文、工具集合和执行生命周期的？

Plugin 中的：

hooks/hooks.json .mcp.json .lsp.json

为什么不是简单地进入 Prompt，而是分别接入生命周期事件、外部工具系统和代码智能系统？

这一篇，我们沿着下面这条运行链继续分析：

Plugin 已安装并启用 ↓ Harness 解析作用域配置 ↓ 定位 Plugin Cache ↓ 读取 Plugin Manifest ↓ 发现并注册各类组件 ↓ 构建 Runtime Capability Registry ↓ 把必要的 Metadata 注入上下文 ↓ 用户显式调用或模型自动匹配 ↓ 执行 Skill / Command / Agent / Hook / MCP / LSP

重点回答：

Plugin 在什么时候被扫描？ Skill Metadata 如何进入模型上下文？ Skill 自动匹配是规则路由还是模型判断？ Command 如何展开成实际 Prompt？ Agent 如何创建独立上下文？ Hook、MCP 和 LSP 如何接入 Runtime？ 多个 Plugin 的能力如何合并和命名？ /reload-plugins 到底重建了什么？

一、从磁盘文件到运行时能力

要理解 Claude Code 的 Plugin 加载机制，首先需要区分三个不同层次。

第一层：Plugin Files → 磁盘上的 Markdown、JSON 和脚本 第二层：Capability Registry → Harness 已经识别并注册的能力描述 第三层：Runtime Execution → 当前任务真正选择和执行的能力

三者并不是一回事。

假设一个 Plugin 中有：

my-plugin/ ├── skills/ │ └── review/ │ └── SKILL.md ├── commands/ │ └── review-pr.md └── agents/ └── reviewer.md

磁盘上出现这些文件，并不等于它们已经全部进入模型上下文。

更准确的过程是：

文件存在 ↓ Harness 扫描并解析 ↓ 提取组件 Metadata ↓ 写入运行时能力注册表 ↓ 根据任务按需加载完整内容

其中，Claude Code 对不同类型组件采用了不同加载方式。

Skill → 先注册描述，匹配后再加载正文 Command → 注册显式调用入口，调用时展开正文 Agent → 注册独立执行角色，调用时创建子上下文 Hook → 注册生命周期监听器，事件发生时执行 MCP → 建立外部 Server 连接，注册 Tools 和 Prompts LSP → 启动语言服务器，注册代码导航和诊断能力

所以 Plugin Loader 并不是简单地把整个 Plugin 目录拼进 System Prompt。

它更像一个多类型能力装配器：

Plugin Loader ├── Skill Registry ├── Command Registry ├── Agent Registry ├── Hook Dispatcher ├── MCP Server Manager └── LSP Server Manager

二、Plugin 在什么时候被扫描

1. 首次 Session 启动

当 Claude Code 启动一个新 Session 时，需要先解析当前环境中的 Plugin 配置。

这些配置可能来自：

Managed Settings User Settings Project Settings Local Settings

其中enabledPlugins使用：

plugin-name@marketplace-name

作为 Plugin 的完整标识。官方配置文档确认，Plugin 可以在用户级和项目级配置中启用或禁用；如果多个作用域存在配置，Claude Code 会按照其配置作用域规则解析最终状态。

一个典型配置是：

{"enabledPlugins":{"plugin-dev@claude-plugins-official":true,"formatter@company-tools":true,"experimental-agent@lab-tools":false}}

Harness 首先需要计算：

哪些 Plugin 最终启用 哪些 Plugin 被当前作用域覆盖为禁用 哪些 Plugin 来自 Managed Policy

得到启用列表后，才会定位 Plugin 的本地安装目录：

~/.claude/plugins/cache/ └── <marketplace>/ └── <plugin>/ └── <version>/

2. Plugin 安装后不会自动修改当前上下文

Plugin 被安装到本地 Cache 后，文件已经存在，但当前 Session 不一定立即感知。

官方 Marketplace 教程在安装 Plugin 后明确要求执行：

/reload-plugins

以便在当前 Session 激活新 Plugin。

因此需要区分：

Plugin Installation → 改变磁盘状态和配置状态 Plugin Loading → 改变当前 Session 的能力状态

如果不执行重载，也不重新启动 Session，当前运行时仍可能继续使用旧的能力注册表。

3. Session 重启时重新加载

重新启动 Claude Code Session 时，Harness 会根据当前配置重新加载已启用 Plugin。

这一过程大致包括：

读取 Settings ↓ 解析 enabledPlugins ↓ 定位 Plugin Cache ↓ 读取 plugin.json ↓ 发现组件 ↓ 建立 Runtime Registry

不过需要说明：

Anthropic 公开文档描述了 Plugin 的组件加载结果和配置方式，但没有完整公开 Plugin Loader 内部函数级实现。

因此，本文讨论的是根据官方行为和配置规范还原出的逻辑过程，而不是对 Claude Code 二进制内部源码的逐行解读。

4. Safe Mode 会跳过 Plugin 能力

Claude Code 当前提供：

claude --safe-mode

Safe Mode 会禁用包括 Plugin、Skill、Hook、MCP Server、Custom Command、Agent 和 LSP Server 在内的自定义能力，同时保留内置工具、权限系统和基础认证。

这从另一个角度说明：

Plugin Registry → 是 Session 初始化期间装配的独立扩展层 Built-in Runtime → 即使没有 Plugin 仍可运行

其架构关系可以理解为：

Claude Code Core ↓ Built-in Tools / Agent Loop / Permissions ↓ Customization Loader ├── CLAUDE.md ├── Skills ├── Commands ├── Agents ├── Hooks ├── MCP ├── LSP └── Plugins

三、Harness 如何发现 Plugin 中的组件

Claude Code Plugin 采用“标准目录自动发现 + Manifest 补充配置”的模式。

一个典型 Plugin 结构是：

my-plugin/ ├── .claude-plugin/ │ └── plugin.json ├── skills/ ├── commands/ ├── agents/ ├── hooks/ │ └── hooks.json ├── .mcp.json └── .lsp.json

Harness 读取 Plugin 后，会根据不同组件类型分别处理。

1. 读取plugin.json

plugin.json首先提供 Plugin 级身份：

{"name":"my-plugin","version":"1.0.0","description":"Development utilities"}

它解决的是：

当前目录属于哪个 Plugin Plugin 的逻辑名称是什么 Plugin 的版本是什么 是否有额外组件声明

Marketplace 还支持strict模式，用于决定 Plugin 自己的plugin.json与 Marketplace Entry 中的组件定义如何合并。

官方文档说明：

strict = true → 默认模式 → plugin.json 是组件定义权威 → Marketplace Entry 可以补充组件 strict = false → Marketplace Entry 是完整定义 → 如果 Plugin 自身又声明组件，可能形成冲突

这说明 Claude Code 并不总是只扫描 Plugin 目录；在部分 Marketplace 策略中，Marketplace Operator 也可以控制哪些组件实际暴露。

2. 扫描标准组件目录

在普通 Plugin 中，Harness 会识别：

skills/ commands/ agents/ hooks/hooks.json .mcp.json .lsp.json

Marketplace 也允许通过配置指向额外的 Command、Agent 或其他组件路径，路径相对于 Plugin Root 解析。

因此，组件来源可能包括：

标准目录自动发现 + plugin.json 显式配置 + marketplace.json 补充配置

最终形成一个归一化 Plugin Descriptor：

NormalizedPlugin ├── id ├── version ├── rootPath ├── skills[] ├── commands[] ├── agents[] ├── hooks[] ├── mcpServers[] └── lspServers[]

这一步的目标，是把不同来源的目录和配置转成统一的运行时描述。

四、Skill Metadata 如何进入上下文

Skill 是 Claude Code Plugin 中最典型的“渐进式上下文能力”。

它的加载过程可以分为两个阶段：

发现阶段 → 只让 Claude 知道有哪些 Skill 执行阶段 → 再加载完整 SKILL.md

1. 启动时不加载全部 Skill 正文

官方 Skill 文档明确说明：

在普通 Session 中，Skill 的描述会被加载到上下文，使 Claude 知道当前有哪些 Skill；完整