企业官网建设流程全解析

1. 从零搭一个 Claude Code 插件市场，先搞清楚它到底在解决什么问题

Claude Code 的插件市场（marketplace）本质上是一个 Git 仓库，里面放着一份marketplace.json作为索引，再按约定把每个插件塞进独立子目录。用户通过/plugin marketplace add把这个仓库挂进来，再用/plugin install 插件名@市场名安装具体插件。它解决的问题很直接：团队内部想共享 hooks、skills、脚本，又不想让每个人手动拷贝目录、改配置，那就用一个仓库统一分发。

适合谁？如果你正在做团队级 Claude Code 能力沉淀，比如统一代码规范检查 hook、共享某个业务领域的 skill、把常用脚本打包成插件，这套结构就是为你准备的。我试过把一个仓库拆成三个插件分别维护，最后发现配置骨架没搭对，安装时一直报找不到插件，所以这篇把marketplace.json、plugin.json、git-subdir三件事一次讲透。

核心检索词先摆出来：Claude Code 插件市场、marketplace.json、plugin.json、git-subdir。这四个词贯穿全文，你跟着目录结构和配置片段走一遍，本地就能跑通加载与校验。

2. TaoToken 前置：把模型接入和插件调试串起来

插件市场本身是本地 Git 仓库的事，但插件里的 hooks、skills 最终要调用模型能力，调试阶段你大概率需要一个稳定的 API 入口。TaoToken 在这里的角色是提供模型调用通道，让你在验证插件行为时不用来回切换配置。

官网入口：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

API 地址：https://taotoken.net/api（这个不加 UTM，直接用于配置）

如果你只是想让插件里的脚本能调通模型，先去控制台拿一个 API Key：

• 控制台：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite
• API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite

拿到 Key 之后，插件里的脚本或 hook 就可以通过https://taotoken.net/api这个 base URL 发起请求。注意，插件市场配置和模型接入是两条线，不要混在一起：市场配置管的是「插件从哪来」，模型接入管的是「插件跑起来调谁」。把这两件事分开，排障时思路会清晰很多。

如果你后续要做长期编码或 Agent 类插件，可以了解 Coding Plan：

https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite

想先验证模型对话行为，用模型对话页快速试：

https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite

接入文档在这里，配置参数以文档为准：

https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

3. 可复制配置：目录结构、marketplace.json 与 plugin.json 骨架

3.1 目录结构长什么样

一个 Git 仓库可以包含多个插件，每个插件放在plugins/下的独立子目录。推荐结构如下：

marketplace-repo/ ├── .claude-plugin/ │ └── marketplace.json # 市场定义，唯一必需的索引文件 ├── plugins/ │ ├── plugin-a/ │ │ ├── .claude-plugin/ │ │ │ └── plugin.json # 插件 A 的元信息 │ │ ├── hooks/ │ │ ├── scripts/ │ │ └── skills/ │ ├── plugin-b/ │ │ ├── .claude-plugin/ │ │ │ └── plugin.json │ │ └── skills/ │ └── plugin-c/ │ ├── .claude-plugin/ │ │ └── plugin.json │ └── scripts/ └── dist/ # 打包输出目录，可选

关键点：.claude-plugin/marketplace.json在仓库根目录，每个插件的.claude-plugin/plugin.json在各自子目录里。两层.claude-plugin不要搞混，这是最常见的目录层级错误。

3.2 marketplace.json 怎么写

市场只需要一个配置文件，放在仓库根的.claude-plugin/marketplace.json：

{ "name": "my-marketplace", "plugins": [ { "name": "plugin-a", "source": "./plugins/plugin-a", "description": "插件 A：统一代码规范检查", "version": "0.0.1" }, { "name": "plugin-b", "source": "./plugins/plugin-b", "description": "插件 B：业务领域 skill 集合", "version": "0.0.1" } ] }

source用相对路径即可，无论本地安装还是远程安装都适用。不需要额外创建marketplace-remote.json，Claude Code 会先 clone 仓库，再基于 clone 后的本地目录解析相对路径。

3.3 plugin.json 怎么写

每个插件必须有.claude-plugin/plugin.json，定义插件元信息：

{ "name": "plugin-a", "version": "0.0.1", "description": "统一代码规范检查插件", "author": "your-team", "hooks": "./hooks", "skills": "./skills" }

name要和marketplace.json里注册的名字一致，否则安装时会报找不到。hooks、skills指向插件内的相对目录，按你实际结构填。

3.4 安装与本地调试命令

用户安装是两步：

# 1. 添加市场源（一次性） /plugin marketplace add git@your-git-server.com:org/marketplace-repo.git # 2. 安装具体插件 /plugin install plugin-a@my-marketplace

本地开发调试时，直接把路径指过去：

/plugin marketplace add /path/to/local/marketplace-repo /plugin install plugin-a@my-marketplace

本地路径方式适合改完配置立刻验证，不用 push 到远程。

4. git-subdir 机制与验证请求：确认插件真的被正确提取

4.1 git-subdir 到底做了什么

当用户通过 Git URL 添加市场后，安装插件时 Claude Code 使用 git-subdir 机制，流程是：

1. clone 整个仓库到本地缓存
2. 定位到插件子目录，比如plugins/plugin-a
3. 提取该子目录作为插件内容安装

这就是「一个仓库、多个插件」能工作的原因。你不需要为每个插件单独建仓库，source的相对路径就是子目录定位依据。

4.2 验证插件是否加载成功

添加市场后，先确认市场被识别：

/plugin marketplace list

应该能看到my-marketplace。然后安装插件：

/plugin install plugin-a@my-marketplace

安装完成后，检查插件目录是否被正确提取。本地调试时可以直接看缓存目录，确认plugin.json被读取、hooks和skills目录存在。如果插件里有 hook 脚本，触发一次对应操作，观察脚本是否执行。

4.3 SSH 与 HTTPS 的踩坑与 insteadOf 修复

这是最容易卡住的地方。现象对照：

根因是 Claude Code 在处理 git-subdir 源时，会内部将 SSH 地址转换为 HTTP 地址进行 clone。如果内网 Git 平台的 HTTP 服务返回重定向或格式不兼容，clone 就失败。转换链路大致是：

git@server.com:org/repo.git ↓ Claude Code 内部 SSH→HTTP 转换 http://server.com/org/repo.git ↓ 平台 HTTP 重定向 http://other-domain.com/path/org/repo.git ← 不可用

解决方案是用 Git 的insteadOfURL 重写机制，把错误的 HTTP 地址拦截并替换回 SSH：

git config --global url."git@your-git-server.com:".insteadOf "http://redirected-domain.com/path/"

原理是 Git 在发起网络请求前先检查 URL 是否匹配insteadOf规则，匹配则做前缀替换：

输入: http://redirected-domain.com/path/org/repo.git 匹配: http://redirected-domain.com/path/ 替换为: git@your-git-server.com: 结果: git@your-git-server.com:org/repo.git ← 走 SSH，正常工作

注意三点：这条规则每个团队成员都要配置一次；建议写进 README 的前置配置步骤；只做前缀替换，后面的路径部分原样保留。

5. 本篇常见错排查

5.1 marketplace.json 和 marketplace-remote.json 都需要吗

不需要。只保留marketplace.json即可。Claude Code 通过 Git URL 添加市场时会先 clone 仓库，然后读取marketplace.json，其中的相对路径基于 clone 后的本地目录解析。多建一个 remote 文件反而容易造成索引混乱。

5.2 安装时报找不到插件

先查三处：marketplace.json里plugins数组是否注册了该插件；source相对路径是否指向真实存在的子目录；插件子目录下是否有.claude-plugin/plugin.json。这三处任一缺失都会导致安装失败。

5.3 HTTPS 认证失败怎么办

如果内网 Git 平台不支持匿名 HTTPS clone，直接用 SSH 地址加insteadOf配置方案。不要试图在 HTTPS 上反复试认证，方向不对。

5.4 更新插件后用户怎么拿最新版

把代码 push 到 Git 仓库后，用户重新执行/plugin install即可拉取最新版本。如果用户本地有缓存，确认缓存刷新后再安装。

5.5 发布前 Checklist

• 插件目录下有.claude-plugin/plugin.json
• marketplace.json中已注册该插件
• 代码已 push 到远程 Git 仓库
• README 中包含前置配置说明（如需要insteadOf）
• 团队成员已配置 Git URL 重写规则

6. 继续把插件跑通：模型接入与文档入口

插件骨架搭好、本地加载验证通过之后，下一步就是让插件里的 hooks 和 skills 真正调通模型。这时候你需要一个稳定的 API 入口，把 base URL 配成https://taotoken.net/api，Key 从 API Keys 页面拿：

https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite

配置参数和接入细节以官方文档为准，遇到请求格式、鉴权头、模型名这类问题，先翻文档再动手改：

https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

如果你要验证插件里某个 skill 的对话行为是否符合预期，用模型对话页快速试一轮，比在插件里反复触发要快：

https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite

长期做编码类或 Agent 类插件，Coding Plan 的额度模型更适合持续调试：

https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite

最后提醒一句：insteadOf规则只做前缀替换，路径部分原样保留，配错前缀会导致所有 Git 请求被错误重写。配完先用git ls-remote验证一次再让团队铺开。