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-modeSafe 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.jsonHarness 读取 Plugin 后，会根据不同组件类型分别处理。1. 读取plugin.jsonplugin.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.jsonMarketplace 也允许通过配置指向额外的 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.md1. 启动时不加载全部 Skill 正文官方 Skill 文档明确说明：在普通 Session 中，Skill 的描述会被加载到上下文，使 Claude 知道当前有哪些 Skill；完整