企业官网建设流程全解析

Claude Code 最被低估的功能，我一直觉得不是它那套对话式编程，而是它的插件系统。很多人装完 claude code，跑两个 demo 就扔在一边，压根没碰过 /plugin 命令，更不知道 plugins 能把自己的工作流整个托管给这个 CLI。这篇东西我不想写成官方文档的翻译，而是从一个天天用 Claude Code 干活的开发者角度，把插件机制掰开揉碎，从它解决什么问题、怎么装、怎么写，到那些你一定会撞上的报错，一次说清楚。适合想认真把 Claude Code 用起来的开发者、正在做团队规范落地的技术负责人，以及那些在 VSCode 里折腾半天只为了少敲几行命令的效率党。

1. Claude Code 的插件机制：先搞清楚它在整个体系里的位置

1.1 plugins 到底能干什么

很多人对 "插件" 的第一反应是"装个好看的皮肤"或者"加个快捷键"，但 Claude Code 的插件完全不是这个路子。它的插件本质上是一个能力包，打包了四类东西：斜杠命令、子代理、钩子和技能。

• 斜杠命令（slash commands）：你在对话框里输入/commit、/review这种命令，背后可以对应一段精心设计的 prompt 甚至是脚本逻辑。这是最直观的插件入口。
• 子代理（subagents）：一个插件可以声明若干个专职小助手，比如"代码审查员""测试用例生成器""提交信息规范员"，每个都有独立的 system prompt，干活的时候由主对话调度它们。
• 钩子（hooks）：这是我最看重的部分。Claude Code 在调用工具的前后会触发事件，比如 Bash 执行前、文件写入后、收到用户输入时。插件可以在事件点挂上自己的脚本，做一个校验、拦截或者通知。
• 技能（skills）：一套结构化的 instructions，告诉模型"遇到这类任务按这个流程来"，技能通常还包括参考文档和示例，比单纯在 prompt 里写要求更可靠。

用生活类比：如果说 Claude Code 是一台没装软件的电脑，那插件就是一个个安装包。每个安装包自带"安装清单"（plugin.json），告诉系统"我有这些命令、这些子代理、这些钩子"，装完就在终端里多出一组长期可用的能力。

1.2 官方插件生态的组成：marketplace、plugin、skill 的关系

术语容易绕晕，我先捋一下。marketplace（插件市场）是一个索引文件，通常托管在 GitHub 仓库里，它指向一揽子插件。plugin（插件）是一个带.claude-plugin元数据目录的仓库或文件夹。skill（技能）是插件内部的单元，也可以脱离插件单独挂在.claude/skills下。

官方生态在 0.2.x 版本之后迅速成型，你可以在claude交互界面里输入/plugin打开管理面板，也可以直接用claude plugin marketplace add owner/repo命令添加一个市场。Anthropic 官方维护的市场是anthropics/claude-code，里面有不少第一方插件，社区里还有大量第三方市场，比如专门做 agent 编排的、做文档生成的。

1.3 什么场景真正值得用插件

我见过不少人把配置塞进~/.claude/settings.json，什么 prompt 都往CLAUDE.md里堆，最后对话越来越卡、行为不可控。插件的价值恰恰是"把一次性 prompt 变成可复用、可分发、可版本管理的资产"。

举个例子，我们组做过一个 PR review 插件：它声明了一个review斜杠命令，内部把一个 code review 子代理的 prompt 和三段式审查清单打包在一起。任何人 clone 仓库后只要装这个插件，就能得到完全一致的审查标准。这种一致性，靠嘴传、靠文档、靠复制粘贴 prompt 都做不到。

另一个值得用的场景是团队通知。Claude Code 有个Notification钩子，任务结束或出错时可以触发外部脚本。我们用这个把耗时的测试任务结果推送到飞书群，不用一直盯终端。这类集成非常适合用插件固化下来，而不是让每个人手动配环境变量。

2. 环境搭建：从安装到第一次跑通插件

2.1 三种安装 Claude Code 的方式，选哪个

官方给的方式有三种：npm 全局包、桌面版安装器、VSCode 扩展。

npm 方式最通用：

npm install -g @anthropic-ai/claude-code

安装完验证版本：

claude --version

如果 npm 下载慢或者公司内网有代理限制，先把 registry 切到镜像源再装：

npm config set registry https://registry.npmmirror.com npm install -g @anthropic-ai/claude-code

桌面版是给不想碰 Node 的人准备的，去官网下载对应平台的安装包，装完会有独立的 Claude Code 桌面应用。VSCode 扩展适合浏览器党，直接在扩展市场搜 Claude Code for VSCode，装完侧边栏会出现一个对话面板，底层调用的还是同一套 CLI。

注意：如果你是在 Windows 上走 npm 安装后claude命令不生效，八成是 PATH 问题，后面专门讲。

2.2 模型接入配置：官方 API 与第三方兼容接口

插件本身不决定模型，Claude Code 的模型来源在配置层决定。两种常见接法：

第一种，直接用官方 API，登录即可：

claude # 第一次启动会让你选择登录方式，或用 ANTHROPIC_API_KEY export ANTHROPIC_API_KEY=sk-ant-xxxx

第二种，接第三方 OpenAI 兼容或 Anthropic 兼容网关。这里必须点名一个很多人问的方案：把 Claude Code 接到 DeepSeek。DeepSeek 官方提供了一个 Anthropic 兼容端点，直接在环境变量里指过去就行：

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN=sk-你的DeepSeekKey export ANTHROPIC_MODEL=deepseek-chat

这样启动claude，底层模型就是 DeepSeek，日常写代码、改 bug 完全够用。deepseek-reasoner也可以试，长任务、复杂推理会更稳，但响应慢一些。我自己的习惯是：日常对话用deepseek-chat，跑批量脚本和代码审查切deepseek-reasoner。

如果不想每次开终端都 export 一堆变量，就把环境变量写进~/.claude/settings.json的env字段：

{ "env": { "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic", "ANTHROPIC_AUTH_TOKEN": "sk-xxx", "ANTHROPIC_MODEL": "deepseek-chat" } }

2.3 添加插件市场并安装第一个插件

装插件第一步是添加市场。在 Claude Code 对话框里：

/plugin

跟着交互面板走，粘贴owner/repo格式的市场地址。也可以命令行操作：

claude plugin marketplace add anthropics/claude-code claude plugin install code-review

装完确认一下：

claude plugin list

这时打开对话输入/，就能看到插件提供的命令出现在斜杠命令列表里。插件安装后存储在~/.claude/plugins/下，结构分marketplaces/和installed/两块，后者是真正的插件本体。

2.4 Windows 下 "claude 命令无法识别" 的根治办法

这个坑太典型了。Windows 用户用 npm 装完claude，打开 PowerShell 敲claude报：

claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

原因很简单：npm 全局包的 bin 目录没有加进系统 PATH。先查 npm 的全局目录：

npm config get prefix

通常输出C:\Users\你的用户名\AppData\Roaming\npm。把这个路径加进环境变量 PATH，然后重新开一个终端。如果是 PowerShell：

$env:Path += ";$env:APPDATA\npm"

注意这只对当前会话有效，永久生效要去"系统属性-环境变量"里加。加完再claude --version就不会报错了。这一步不解决，后面所有插件命令都是空中楼阁。

3. 手写一个插件：从 JSON 骨架到第一个斜杠命令

3.1 插件目录结构长什么样

一个最小插件，目录结构如下：

my-plugin/ ├── .claude-plugin/ │ ├── plugin.json │ └── commands/ │ └── commit.md └── CLAUDE.md

.claude-plugin是插件身份标识，Claude Code 识别插件就看这个目录是否存在。plugin.json是清单，commands/下面是斜杠命令对应的 markdown prompt 文件。插件还可以有hooks/、agents/、skills/、scripts/这些子目录，按需创建。

3.2 plugin.json 字段解读

plugin.json是最容易写错的文件，我先把常用字段列全：

{ "name": "commit-helper", "version": "0.1.0", "description": "生成符合 Conventional Commits 规范的提交信息", "author": "your-name", "license": "MIT", "commands": { "commit": { "description": "根据 git diff 生成提交信息", "agent": "main", "skill": "commands/commit.md" } }, "hooks": { "Stop": [ { "matcher": "", "command": "node scripts/notify.js" } ] } }

字段说明：

commands里的skill字段指向一个 markdown 文件，这个文件就是命令触发后模型要执行的指令。agent字段一般写"main"，表示由主助手执行这个命令。

3.3 实现一个生成 commit message 的斜杠命令

写一个实用的：每次提交前让它根据git diff生成 conventional commit 信息。

第一步，建commands/commit.md：

--- description: 根据 git diff 生成符合 Conventional Commits 规范的提交信息 agent: main --- 请执行以下步骤： 1. 运行 `git diff --stat` 观察变更范围。 2. 运行 `git diff` 获取具体改动。 3. 分析改动类型，决定 commit type：feat / fix / docs / style / refactor / test / chore。 4. 以 Conventional Commits 格式输出提交信息候选项，最多三个，每个之间用空行隔开。 5. 如果检测到破坏性变更，在提交信息末尾加上 `BREAKING CHANGE:` 说明。

第二步，在plugin.json的commands里注册：

{ "commands": { "commit": { "description": "生成提交信息", "agent": "main", "skill": "commands/commit.md" } } }

第三步，本地加载测试。在 Claude Code 对话中输入：

/plugin install /path/to/my-plugin

也可以直接/plugin面板里选"Install local plugin"。装完后输入/commit，Claude Code 会自动执行 git diff 并输出提交信息候选项。整个过程不需要写一行脚本代码，纯 prompt 编排就完成了。

3.4 从 GitHub 手动安装 skills

经常有人在 GitHub 上看到一个好的 skill 仓库，不知道该怎么塞进自己的 Claude Code。手动安装其实很简单。

一个 skill 就是一个目录，里面有SKILL.md。把整个目录复制到用户级技能目录：

# 创建目录 mkdir -p ~/.claude/skills/code-reviewer # 把 skill 内容放进去 cp -r /path/to/code-reviewer/* ~/.claude/skills/code-reviewer/

核心是确认根目录下的SKILL.md里 frontmatter 字段写全：

--- name: code-reviewer description: 对指定代码做深度审查，输出按严重程度分级的问题清单 ---

然后在CLAUDE.md项目记忆文件里挂引用，比如：

## 技能 - @code-reviewer 用于 PR 审查

重启 Claude Code 会话后，模型就能在合适的场景自动调用这个 skill，或者在对话里用斜杠/code-reviewer唤起。这个方法用来装那些只发了 GitHub 仓库、还没做成 market 的 skill 特别方便。

3.5 用 ccswitch 管理多套配置

当你既要用官方 key 干活，又要接 DeepSeek，还要连公司内网网关，手工改环境变量真的会崩溃。ccswitch 就是干这个的，它的作用是在一套配置文件和多个 profile 之间快速切换。

安装后先添加 profile：

ccswitch add official --api-key sk-ant-xxxx ccswitch add deepseek --base-url https://api.deepseek.com/anthropic --auth-token sk-deepseek-xxx --model deepseek-chat

列出并切换：

ccswitch list ccswitch use deepseek

切换后 ccswitch 会重写~/.claude/settings.json里的env字段，再启动claude就是新的模型配置。它的配置文件在~/.ccswitch/config.json，里面是一个 profile 数组，格式跟上面我写的差不多。多配置场景下，这是比手改 JSON 靠谱得多的方案。

4. 插件踩坑与典型报错排查实录

4.1 harness failed to load plugins 到底在说什么

这个报错可能是最近社区里出现频率最高的：

harness failed to load plugins web boot: 2 entries did not activate

第一次看到的人会以为 Claude Code 崩了，但其实它说的是：插件宿主环境（harness）在启动加载阶段发现有两个插件条目没有激活。web boot指的是插件系统内部加载器的引导阶段，"did not activate" 表示声明了、但启动时初始化失败。

常见原因我列个速查表：

排查步骤按顺序来：

1. 跑claude doctor，它会检查配置和插件状态。
2. 看日志~/.claude/logs/，里面会有具体哪个插件加载失败。
3. 用/plugin uninstall逐个卸载最近安装的插件，直到错误消失。

这个报错还有一个很隐蔽的来源：手工修改了插件目录里的文件，比如把commands/commit.md删了但plugin.json还注册着。所以先检查那些手动装的插件，大概率是文件没放全。

4.2 api error 400：配置错误，缺少 base_url

这个报错多半出在配了第三方模型之后。完整提示类似：

api error: 400 配置错误: claude provider 缺少 base_url 配置

含义非常明确：provider 被选中了，但 provider 配置里没给网关地址。最常见的触发场景是 ccswitch 切到了一个没填base_url的 profile，或者环境变量里ANTHROPIC_BASE_URL为空。

解决路径：

# 检查当前环境变量 echo $ANTHROPIC_BASE_URL # 如果为空，要么 export，要么通过 ccswitch 补 base_url ccswitch edit <profile-name>

还有一种是~/.claude/settings.json里的env被覆盖了。VSCode 里配过 Claude Code 的要注意，VSCode 扩展的配置优先级很高，可能把终端里 export 的变量盖掉。检查 VSCodesettings.json里有没有残留的"ANTHROPIC_BASE_URL": ""，有就删掉。

4.3 插件装了却没生效的排查

明明/plugin list里有插件，但输入斜杠命令却提示找不到。这种情况先确认命令名的大小写和拼写。命令名是大小写敏感的，/Commit和/commit不完全是一回事。

其次是权限问题。插件命令如果声明了permission字段，首次执行会弹权限确认，在无人值守或 hook 场景下会被静默拒绝。检查~/.claude/settings.json里的permissions配置，给插件开白名单：

{ "permissions": { "allow": [ "Bash", "Read", "Write" ] } }

还有一种低级错误：插件目录权限不对。特别是 Linux 下从别人 repo 里拷过来的插件，plugin.json可能是 root 用户所有，当前用户读不了。chmod -R u+r解决。

4.4 飞书或其他 IM 通知集成的实用做法

很多人想把 Claude Code 的长任务结果推到飞书，省得盯终端。做法不复杂，用Notification钩子，挂一个 Node 脚本：

# 在 plugin.json 声明钩子 "hooks": { "Notification": [ { "command": "node scripts/notify-feishu.js" } ] }

脚本内容示意：

const webhook = process.env.FEISHU_WEBHOOK_URL; const payload = { msg_type: 'text', content: { text: `Claude Code 任务结束：${process.env.CLAUDE_TASK_END_STATUS}` } }; fetch(webhook, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload), });

这里的CLAUDE_TASK_END_STATUS是 Claude Code 在钩子环境里放的变量，具体名称以你安装版本为准，可以在日志里看到。飞书群机器人 webhook 地址在飞书群里创建机器人就能拿到。没有飞书就换成企业微信或钉钉，逻辑一模一样。

4.5 从大上下文到嵌入式：几个我实测过的真实场景

Claude Code 支持把上下文窗口推到 1M token 之后，插件加载能力上限一下子被拉高了。我们试过把整个 monorepo 的目录结构生成分析报告再让子代理逐目录审查，效果比以前分多次对话好得多，上下文不中断，插件能持续引用之前的结论。

嵌入式方向也有朋友在玩 STM32。我之前看到有人把编译错误匹配器做成了插件，钩子挂在PostToolUse上，检测到编译输出里的错误代码时自动查手册、给出修复建议。这种场景用插件封装比每次手动贴错误给模型靠谱得多，因为钩子能保证在错误发生的第一时间触发，不会被对话上下文冲掉。

结尾：一点实操心得

整套插件的思路跑通之后，我开始理解官方把它做成 marketplace 的用意了。CLI 工具如果只是对话，每次的聪明都是一次性的；插件做的是把聪明沉淀下来。我现在的建议是：先从/plugin里装一两个官方插件跑熟，再手动装一个 GitHub 上的 skill 感受一下知识包的作用，最后再下手写自己的插件。写的时候不要贪多，先做一个斜杠命令，跑通本地安装链路，等目录结构、文件引用这些基本功都对了，再加 hooks、加子代理。插件报错大部分不是逻辑问题，而是路径和格式问题，记住这点，排查时就不会慌。