企业官网建设流程全解析

解剖 Academic Forge 技能注册表：registry/skills.json 结构与 sparse-checkout 安装机制

【免费下载链接】AcademicForgeOne Forge, All Skills: A curated skill collection for academic writing and research. 点开即用，按需配置的一站式学术研究skills平台。项目地址: https://gitcode.com/gh_mirrors/ac/AcademicForge

Academic Forge 是一个一站式学术 skill 选配与安装平台，为 Claude Code / OpenCode / Codex 提供科研写作、图表可视化、蛋白质结构预测等现成技能包。它的核心枢纽是技能注册表 registry/skills.json：一份约 7000 行的 JSON 目录，描述了 12 个技能包、306 个可安装条目，并用install字段声明每个条目的拉取方式（整仓克隆或 sparse-checkout 稀疏检出），让安装脚本 scripts/forge-install.sh 能够"读表即装"。

本文带你完整解剖这份注册表的数据结构、两种安装机制的原理，以及配套的校验与发布链路。🧐

🗂️ 注册表顶层结构：一切皆"技能包"

打开 registry/skills.json，顶层只有一个键：

{ "skills": [ /* 12 个技能包记录 */ ] }

每个技能包（pack）记录包含以下字段：

其中stars字段由 scripts/refresh-stars.mjs 定期刷新，保证站点展示的数据是新鲜的。⭐

🔑 安装机制：git-clone 与 sparse-checkout 双轨

注册表最有价值的部分是每个条目的install对象，目前支持两种method：

方式一：git-clone整仓克隆

"install": { "method": "git-clone", "url": "..." }

适用于"整个仓库就是一个技能"或需要完整内容的集合型包（如 149 个科研技能的 Scientific Agent Skills、98 个的 AI Research Skills）。脚本会执行浅克隆（--depth 1），把.git目录删掉后保留纯文件——快且省空间。

方式二：sparse-checkout稀疏检出

"install": { "method": "sparse-checkout", "url": "...", "sparse_path": "skills/claude-science" }

当目标仓库庞大但你只需要其中一两个目录时，sparse-checkout 就是最优解。scripts/forge-install.sh 的实现分四步：

1. 部分克隆：git clone --depth 1 --filter=blob:none --sparse——只拉取提交历史骨架，不下载任何文件内容（blob 按需加载）；
2. 指定检出路径：git sparse-checkout set <sparse_path>，让工作区只物化目标目录；
3. 复制产物：把检出目录的内容拷入你的项目（默认.claude/skills/<id>）；
4. 清理临时目录：整个临时检出区随后删除，不留痕。

以本地维护的claude-science包为例，它正是对本仓库自身做稀疏检出（sparse_path: "skills/claude-science"），一条命令就能把 32 个内置科研技能装进你的项目——这就是"无需订阅、跨 agent 通用"背后省带宽的关键。🚀

💡 两种方式的取舍：仓库小而独立 →git-clone；仓库大而只需要局部 →sparse-checkout。注册表里 4 个包走稀疏检出，8 个包走整仓克隆。

📦 集合型包与 sub_skills：306 个条目的由来

大集合包通过is_collection: true+sub_skills数组展开为可单独安装的子条目：

每个sub_skills条目有自己的id（带前缀，如cs.algorithmic-art，防止跨包重名）、双语summary、category/subdiscipline分类，以及独立的install对象。这意味着你可以整包安装，也可以精确到单个技能——--skills cs.diffdock只会检出那一个目录。12 个包 + 300 余个子条目，正是站点 site/public/index.slim.json 中 306 个条目的来源。

子条目还允许声明post_install钩子，例如 Scientific Agent Skills 的clean_ads：安装后自动从所有SKILL.md中剔除源仓库夹带的推广章节（scripts/forge-install.sh 中的post_clean_ads函数实现）。

🎯 从注册表到终端：一条安装命令的旅程

站点端的类型定义在 site/src/lib/registry.ts，与 JSON 结构一一对应。你在选配页勾选技能后，site/src/lib/install-command.mjs 会拼出一条可复制的命令：

# macOS / Linux：--tool 决定目标工具（claude/opencode/codex） curl -sSL <脚本地址>/forge-install.sh | bash -s -- \ --tool claude \ --skills humanizer,claude-science

脚本执行流程一览：

1. 下载注册表：从远端拉取skills.json到临时文件（scripts/forge-install.sh）；
2. 按 id 查表：内置的json_extract同时匹配顶层包与sub_skills子条目；
3. 按 method 分发：走克隆或稀疏检出分支；
4. 写入工具目录：claude→.claude/skills/，opencode→.opencode/skills/，codex→.codex/skills/；
5. 汇总报告：输出OK / SKIP / FAIL清单，已存在同名技能自动跳过（加--force覆盖）。

Windows 用户有等价的 scripts/forge-install.ps1，参数名大小写略异（-Tool/-Skills）。回归测试则覆盖在 scripts/tests/ 下，如 forge-install-multiple-sparse-checkouts.sh 专门验证一次安装多个稀疏检出包的场景。

✅ 注册表如何保持可信：校验与约束

一份被多方消费（安装脚本、站点、AI agent）的目录，数据质量至关重要。scripts/validate-registry.mjs 对每个条目做四重检查：

• id 全局唯一：跨包与子条目查重，避免安装命令歧义；
• method 合法：只允许git-clone或sparse-checkout，且后者必须带sparse_path；
• 本地包落盘验证：凡指向本仓库的稀疏检出路径，必须在磁盘上真实存在（如skills/claude-science目录），杜绝"目录里写了、仓库里没有"的幽灵条目；
• 翻译一致性：summary.zh不得与summary.en相同，防止漏翻译。

校验不通过即退出码为 1，可无缝接入 CI。配合站点发布产物 site/public/skills.json，就形成了"仓库内单一数据源 → 校验 → 站点展示 + 安装消费"的完整闭环。

📚 小结与延伸阅读

一句话总结：registry/skills.json把"技能从哪里来、怎么装、装到哪"全部声明化，sparse-checkout 则让"大仓库小技能"的安装又快又省。理解了这份注册表，你就理解了 Academic Forge 一键安装的全部秘密。🔧

【免费下载链接】AcademicForgeOne Forge, All Skills: A curated skill collection for academic writing and research. 点开即用，按需配置的一站式学术研究skills平台。项目地址: https://gitcode.com/gh_mirrors/ac/AcademicForge