企业官网建设流程全解析

GPTaku Plugins 是一个面向 Claude Code 的插件市场（plugin marketplace），本文带你从零看懂它的两层仓库架构、插件目录规范，并完整走通一次 marketplace 发布流程——从写好第一个插件文件，到打版本标签、同步市场、最终让用户三条命令装好你的 Claude Code 插件。

市场架构拆解：为什么是“父仓库 + git submodule”双层结构

新手第一次打开 GPTaku Plugins 仓库，最容易困惑的点是：为什么plugins/下面每个插件目录都是空的或独立的？答案在 .gitmodules 里——父仓库（marketplace）只负责“目录 + 指针”，每个插件是一个独立的 git 子模块（submodule），拥有自己的仓库、分支和版本历史。

gptaku_plugins/ # 父仓库 = Claude Code 插件市场 .claude-plugin/ marketplace.json # 市场清单：所有上架插件的注册表 plugins/ # 每个目录是一个独立子模块 insane-search/ insane-research/ pumasi/ ... tools/ # 市场校验与诊断脚本 scripts/ # 发布工作流脚本

这种架构带来三个好处：

• 独立演进：某个插件改代码、发版本，不会污染其他插件；
• 精确指针：父仓库记录的 gitlink（子模块指针）精确指向“市场里正在售卖”的那个 commit；
• 市场可整仓分发：用户只需添加一次市场地址，Claude Code 即可从中安装任意插件。

整个市场就像一个“路由器”：左边是用户撞上的各种墙（打不开的网页、写不出的 PRD、没有审查模型），右边是解锁后的能力，中间由各个 Claude Code 插件完成分流。

开发一个最小Claude Code插件：4个核心文件

以仓库里真实存在的 plugins/insane-crawl/ 为样本，一个可上架的 Claude Code 插件最少由 4 个部分构成：

第1步：写清单文件.claude-plugin/plugin.json

这是插件的“身份证”，必填字段为name、version、description、author、license。以 plugins/insane-crawl/.claude-plugin/plugin.json 为例：

{ "name": "insane-crawl", "version": "0.1.0", "description": "Local, resumable research crawler for public pages...", "author": { "name": "fivetaku" }, "license": "MIT" }

⚠️ 新手常见错误：版本号必须遵循 semver（x.y.z），且name用 kebab-case。市场校验脚本会强制检查这两点。

第2步：写斜杠命令commands/<name>.md

命令文件是“执行指令书”：用户输入/insane-crawl时，Claude Code 会加载它。核心是 frontmatter 里的name、description、allowed-tools，正文则告诉模型如何调用你的引擎。参考 plugins/insane-crawl/commands/insane-crawl.md。

第3步：写技能skills/<name>/SKILL.md

技能是“可被自然语言触发”的能力包。plugins/insane-crawl/skills/insane-crawl/SKILL.md 的 frontmatter 里，description写得越具体（何时用、何时别用），模型触发越准。技能目录里还能放任意可执行代码——例如 insane-crawl 的 Python 引擎（engine/包）和测试（tests/）。

第4步：补齐 README 与 LICENSE

README 说明命令边界、依赖与平台支持，LICENSE 明确开源许可（本市场统一 MIT）。这两项在用户信任决策和上架校验中都会被检查。

注册到marketplace：marketplace.json的4个关键字段

插件写好后，要在市场清单 .claude-plugin/marketplace.json 中登记一个条目，才能被/plugin marketplace发现。每个条目只需 4 个关键字段：

{ "name": "docs-guide", "description": "Fetch and explain official documentation ...", "source": "./plugins/docs-guide", "category": "development", "tags": ["documentation", "llms-txt", "official-docs"] }

注意一个重要的边界：目录存在 ≠ 上架。仓库里未注册的插件（如仍在开发中的insane-crawl）不会出现在市场中，是否公开发布是一个独立的显式决策。

发布全流程：从改代码到用户安装的8步标准作业

GPTaku 团队把发布流程固化成了文档 docs/plugin-release.md，共 8 步。理解它，你就掌握了任何 Claude Code 插件市场的发布套路：

1. 验证改动：在插件子仓库的独立分支上跑测试、实测入口命令，确认无回归；
2. 同步版本号：只升版本不改代码会被视为无效发布；
3. 打 Release 标签：在插件仓库（而非父仓库）创建v<version>标签，且必须指向“实测通过的那个 commit”；
4. 更新父仓库指针：在父仓库只 stageplugins/<plugin-name>，让 gitlink 指向第 3 步的 commit；
5. 同步市场克隆：用户机器上的市场克隆执行git pull --ff-only+submodule update --init plugins/<plugin>；
6. 替换安装缓存：缓存目录按<plugin>/<version>组织，整体替换而非覆盖旧文件；
7. 核对安装元数据：installed_plugins.json里的version与gitCommitSha必须与文件一致；
8. 重载并实测：/reload-plugins后在新会话中实测命令行为。

其中第 1–5 步的“合并 + 指针更新”部分已被 scripts/plugin-release.sh 脚本化，一条命令完成子模块合并、版本校验、父仓库指针提交：

scripts/plugin-release.sh <plugin名> <工作分支> --push

脚本内置了防呆检查：父仓库必须在 main 分支、子模块必须是 tracked 状态、无未提交改动、plugin.json版本必须是合法 semver——任何一项不满足都会直接中止，而不是带着错误状态往下走。

一键校验：两个脚本挡住“缓存不一致”这个头号事故

发布流程中最高频的事故是：版本字符串对了，但内容不是——旧缓存残留、子模块指针没动、清单字段漂移。GPTaku 用两个零依赖脚本做成自动化门禁：

• 市场完整性门禁tools/validate_marketplace.py：校验 marketplace.json 字段 schema、每个条目的 source 目录与 plugin.json 是否存在、name 是否一致、声明的 agents/skills/commands 路径是否真实存在、有没有“tracked 了却没上架”的插件目录。可选--check-releases还能核对远程v<version>标签是否存在；
• 安装诊断器tools/gptaku_doctor.py：对每个已安装插件检查启用状态、缓存版本、隐藏清单、版本元数据、市场克隆 revision 与 hook 文件是否全部对齐，并区分ok / warn / fail / unverified四种状态——“没验证过”不会被悄悄算成“通过”。

# 发布前：市场清单门禁 python3 tools/validate_marketplace.py --check-releases # 安装后：单插件诊断 python3 tools/gptaku_doctor.py <plugin名> --all

新手常见坑与上手清单

🧭上手顺序建议：先读懂 AGENTS.md 里的版本更新检查清单 → 用 README.zh.md 的三条命令装一个现成插件体会用户视角（添加市场 → 安装插件 →/reload-plugins）→ 照着 insane-crawl 的 4 文件结构写自己的插件 → 过校验门禁 → 按 docs/plugin-release.md 走完 8 步发布。

从零到上架，Claude Code 插件并没有想象中神秘：一个清单、一个命令、一个技能、一份注册，再配合严格的“指针—标签—缓存”一致性校验，就是你发布到 marketplace 的全部骨架。