企业官网建设流程全解析

• AI 插件
• 开发工具
• 插件系统

本文围绕 Claude Code 官方插件目录中的 explanatory-output-style 插件，剖析它如何以 SessionStart Hook 的形式重建已废弃的 Explanatory 输出风格：注入教育性洞察指令、引导 Claude 在写码前后输出代码库专属的见解。读完本文，你将掌握该插件的完整行为机制、源码级实现细节，以及如何安装、迁移、禁用和个性化定制这一输出风格插件。

插件定位：输出风格的插件化重建

在 Claude Code 中，"输出风格"（Output Style）曾是一种控制模型输出语调与行为的系统级设置。Explanatory 输出风格即其中之一，其核心诉求是让 Claude 在完成任务的同时，附带提供具有教育意义的解释。该风格被标记为废弃（deprecated）后，explanatory-output-style 插件以新的形态将其复活：把输出风格降级为普通上下文指令，通过插件分发而非系统设置生效。

插件在 README 开篇即给出了明确的定位说明：

This plugin recreates the deprecated Explanatory output style as a SessionStart hook.

这意味着它不再依赖 Claude Code 的系统设置机制，而是完全建立在插件系统的事件钩子（Hook）之上。从仓库结构看，该插件体积极小、职责单一，仅包含三个组成部分：

• hooks/hooks.json —— Hook 注册清单；
• hooks-handlers/session-start.sh —— 实际注入指令的脚本；
• README.md 与 LICENSE —— 使用文档与 Apache 2.0 许可。

核心机制：SessionStart Hook 如何注入额外上下文

Hook 注册清单

插件的全部魔法都从 hooks/hooks.json 开始。该文件注册了一个SessionStart事件钩子，指向插件目录内的 Bash 脚本：

{ "description": "Explanatory mode hook that adds educational insights instructions", "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks-handlers/session-start.sh\"" } ] } ] } }

其中有两个关键点值得展开：

• SessionStart事件：这是 Claude Code 在每次会话启动时触发的事件类型。注册在此事件上的命令会在会话建立之初执行，从而保证指令在模型真正开始处理用户任务之前就已就位。
• ${CLAUDE_PLUGIN_ROOT}环境变量：这是插件系统提供的便携路径变量，运行时会被解析为插件在本地设备上的绝对路径。在 plugin-dev 的开发规范中，${CLAUDE_PLUGIN_ROOT}被明确列为插件开发的标准用法，用于保证 Hook 命令与脚本引用不依赖具体安装位置，从而获得可移植性。

注入脚本与 additionalContext

真正承载输出风格指令的是 hooks-handlers/session-start.sh。该脚本不做任何逻辑判断，职责只有一个：向标准输出打印一段 JSON，通过hookSpecificOutput.additionalContext字段把指令文本注入会话：

#!/usr/bin/env bash # Output the explanatory mode instructions as additionalContext # This mimics the deprecated Explanatory output style cat << 'EOF' { "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": "You are in 'explanatory' output style mode, ..." } } EOF exit 0

脚本以exit 0结束，表示 Hook 执行成功；指令文本则完全依赖cat << 'EOF'的 heredoc 输出。由于使用了带引号的'EOF'分隔符，Bash 不会对文本中的内容做变量展开或命令替换，保证了指令中的反引号、换行等字符被原样传递。

additionalContext字段承载的指令文本，正是插件行为规范的全部来源，其完整内容包括三大部分：

1. 模式声明：明确告诉模型当前处于'explanatory'输出风格模式，应在协助任务的同时提供关于代码库的教育性洞察。
2. 平衡原则：要求模型保持清晰、有教育性，同时聚焦任务本身；允许在提供洞察时适度超出常规长度限制，但必须保持相关与专注。
3. Insight 输出格式：要求模型在写代码前和写代码后，都以固定格式输出 2～3 条关键教育点。

行为细节：插件要求 Claude 做什么

根据 README 与注入脚本，启用该插件后，每次会话开始时 Claude 会自动获得三条行为指引：

1. 提供关于实现选择的教育性洞察（Provide educational insights about implementation choices）；
2. 解释代码库的模式与决策（Explain codebase patterns and decisions）；
3. 在任务完成与学习机会之间保持平衡（Balance task completion with learning opportunities）。

在写代码前后，洞察将以如下固定格式呈现：

`★ Insight ─────────────────────────────────────` [2-3 key educational points] `─────────────────────────────────────────────────`

注入脚本对格式有两处细化要求，属于 README 之外的实现细节：

• 洞察只进入对话，不写入代码库（"These insights should be included in the conversation, not in the codebase"）；
• 洞察应聚焦代码库特有内容而非通用编程概念，并且边写边给，不要等到任务结束才统一输出（"Provide them as you write code"）。

安装与使用：零配置的自动激活

该插件遵循 Claude Code 插件的标准安装方式。安装完成后，hooks.json 注册的 SessionStart Hook 会在每次会话开始时自动触发，指令随之注入，全程无需任何额外配置：

• 激活时机：每个新会话启动时自动生效；
• 配置要求：无，安装即用；
• 适用范围：对会话内所有后续任务持续产生影响。

插件 README 同时给出了一条醒目的警告，属于必须知晓的成本提示：

WARNING: Do not install this plugin unless you are fine with incurring the token cost of this plugin's additional instructions and output.

即：额外的指令注入与洞察输出都会消耗 Token。如果你对每次会话的 Token 成本敏感，安装前需要慎重权衡。

洞察内容指南：什么值得讲，什么不值得讲

插件对洞察的内容取向做了明确界定，这也是该输出风格区别于通用"讲解模式"的关键——它追求代码库专属而非泛泛而谈：

从源码看，注入脚本将这一取向进一步落到了执行层面：要求模型关注"针对刚写的代码或当前代码库的有趣洞察"（interesting insights that are specific to the codebase or the code you just wrote）。这意味着该插件的效果高度依赖具体项目——同一个会话中，项目代码越有特色，洞察的价值越高。

从 Output Styles 迁移：替换废弃配置

如果你此前使用过 Explanatory 输出风格，迁移路径非常直接。旧配置形如：

{ "outputStyle": "Explanatory" }

现在只需安装本插件即可获得等价行为，无需再修改任何系统级配置。插件在语义上完成了从"系统设置"到"插件分发"的迁移，这正是官方对这类废弃功能的推荐处理方式。

与 CLAUDE.md 的等价与差异

README 明确指出：SessionStart Hook 这种模式大致等价于 CLAUDE.md，但更灵活，且能通过插件机制分发。两者对比可以从源码结构得到印证：

• 等价性：SessionStart 注入的additionalContext与 CLAUDE.md 一样，都会成为会话初始上下文的组成部分，在模型处理任务前就已生效；
• 差异点：CLAUDE.md 是仓库内的一份静态文件，无法随插件打包分发、无法跨项目复用；而 Hook 模式可以将整段指令封装进插件，像本插件这样随官方插件目录分发，安装即生效。

边界提醒：软件开发任务之外的输出风格

README 还给出了一条重要的适用边界建议：涉及软件开发之外任务的输出风格，更适合用 Subagents 表达，而不是 SessionStart Hook。理由是两者的作用机制不同：

• Subagents 会替换（change）系统提示词，适用于需要独立人格与任务边界的场景；
• SessionStart Hook 只是在默认系统提示词之上追加（add）内容，适合对模型输出基调做整体调整。

对本插件而言，Explanatory 属于影响整体输出基调的风格，因此 SessionStart Hook 是恰当载体。

从源码结构看实现模式：与姊妹插件的对照

从仓库目录结构可以观察到，explanatory-output-style 并非孤例，它与 learning-output-style 构成了一组对照的"输出风格类"插件：

• 两者共用完全相同的插件骨架：hooks/hooks.json注册 SessionStart、hooks-handlers/session-start.sh输出additionalContext；
• learning-output-style 在 explanatory 功能之上叠加了交互式学习模式，其 session-start.sh 中明确声明"结合了未发布的 Learning 输出风格与 explanatory 功能"。

对照两个插件的注入脚本可以看出该模式的通用套路：把一段风格指令文本放进 heredoc，以 JSON 形式输出给 Hook 系统，指令的差异只体现在additionalContext的文本内容上。这种"配置即代码"的设计使得输出风格可以被版本化、审查和分发。

管理变更：禁用、卸载与个性化

插件 README 在末尾给出了三种管理操作及其语义区分：

其中"更新"路径对希望定制输出风格的开发者最有价值：复制本插件到本地后，直接修改 session-start.sh 中additionalContext的指令文本，即可改变洞察的格式、频率或侧重方向，而无需等待上游更新。README 给出的实践提示是：可以直接让 Claude 阅读 Claude Code 的插件文档，由它代为完成本地化配置。

结语

explanatory-output-style 是一个小而完整的插件范本：它以极少的文件实现了"输出风格插件化"这一核心思路，展示了 SessionStart Hook 注入additionalContext的标准姿势，也印证了插件系统对 CLAUDE.md 场景的补充价值。无论你是想直接获得教育性洞察输出，还是想把它作为模板学习如何编写"注入型"输出风格插件，本插件都值得通读 README、hooks.json 与 session-start.sh 三份核心文件。若需了解插件开发的一般规范，可进一步参考 plugin-dev 与 hook-development 技能。

• AI 插件
• 开发工具
• 插件系统