尧图网页设计 
Academic Forge 本地开发与贡献完全指南从站点预览到 CI 校验和 GitHub Pages 部署【免费下载链接】AcademicForgeOne Forge, All Skills: A curated skill collection for academic writing and research. 点开即用按需配置的一站式学术研究skills平台。项目地址: https://gitcode.com/gh_mirrors/ac/AcademicForgeAcademic Forge是面向 Claude Code / OpenCode / Codex 的学术技能Skill选配与安装平台用户在网页上勾选所需技能包一键生成安装命令即可在自己的项目中使用。这篇文章面向第一次接触本项目的开发者带你完整走一遍本地开发流程安装依赖、预览站点、跑通校验与测试、理解 CI 流水线最后了解 GitHub Pages 的自动部署机制。一、30 秒看懂项目结构在动手之前先花 30 秒建立整体认知后面的每一步你都会知道为什么改这里目录 / 文件作用site/Astro Tailwind 构建的选配站点源码registry/skills.json技能注册表站点和安装器共同的数据源scripts/注册表校验、索引构建、安装脚本skills/本地维护的技能包含 32 个 Claude Science 技能.github/workflows/CI 工作流校验与部署主分支是site-first所有站点、注册表与安装器相关的贡献都基于它进行详见 QUICKSTART.md 与 CONTRIBUTING.md。二、一键完成本地环境准备环境要求Node.js ≥ 22.12.0在 site/package.json 中声明了最低版本CI 使用的也是 22.12.0Git克隆仓库并安装依赖git clone https://gitcode.com/gh_mirrors/ac/AcademicForge cd AcademicForge npm run site:installsite:install是根目录 package.json 定义的快捷脚本实际等价于在site/目录内执行npm install。根目录本身不需要安装依赖所有构建、校验脚本都是零依赖的 Node 脚本。三、最快站点预览方法三步跑起本地站点在仓库根目录依次执行npm run build npm run previewbuild会先执行scripts/build-slim-index.mjs生成轻量索引文件即 site/public/index.slim.json 的来源再调用 Astro 构建静态站点preview启动本地静态服务器浏览器打开后即可看到线上同款站点。如果你希望边改边看可以直接用开发服务器npm run dev 一个小知识站点地址带/AcademicForge前缀是因为它在 site/astro.config.mjs 中配置了base: /AcademicForgeGitHub Pages 项目站点的子路径。本地preview同样会遵守该配置属于正常现象。四、本地复现 CI 校验提交前必跑命令本项目的 CI 核心就是一条命令npm run ci:validate。你可以在提交前本地完整复现 CI 的判定结果避免白等流水线。1. 注册表校验npm run validate:registry它执行 scripts/validate-registry.mjs逐条检查 registry/skills.json典型拦截规则包括skill id 重复install.method不是git-clone/sparse-checkout之一使用sparse-checkout但缺少install.sparse_path本地技能包scientific-visualization、claude-science 及其子技能声明的sparse_path在磁盘上不存在中英文摘要内容完全相同即summary.zh未真正翻译。校验通过的输出是Registry validation passed.任何一条规则不满足都会打印具体错误并以非零码退出。2. 站点与脚本单元测试npm run test它串联两组测试定义见 package.jsontest:site运行 site/src/lib/ 下的*.test.mjs覆盖分类、卡片选择、安装命令生成等站点逻辑test:scripts运行注册表校验器等脚本的测试。两者都基于 Node 内置的node --test运行器无需额外测试框架。3. 一次性全量校验等价于 CInpm run ci:validate该命令依次执行validate:registry→test→build与 CI 校验工作流中的关键步骤一一对应。4. 改动安装器时追加冒烟测试如果你修改了 scripts/forge-install.sh 或 scripts/forge-install.ps1CONTRIBUTING.md 要求额外运行本地安装器冒烟测试bash scripts/tests/forge-install-local-registry.sh pwsh -File scripts/tests/forge-install-local-registry.ps1另有 scripts/tests/forge-install-multiple-sparse-checkouts.sh 用于验证多技能 sparse-checkout 安装场景CI 也会执行它。五、理解 CI校验流水线在做什么项目的 CI 由两个独立工作流组成目录为 .github/workflows/。1. 校验工作流 validate.yml触发条件push 或 pull_request 指向site-first分支且改动路径命中registry/、scripts/、site/、skills/scientific-visualization/、skills/claude-science/或根目录package.json。流水线步骤检出代码并用 Node 22.12.0 初始化环境带 npm 缓存执行npm ci --prefix site安装站点依赖执行npm run ci:validate即上文的校验 测试 构建全量流程依次运行本地注册表安装冒烟测试与多 sparse-checkout 冒烟测试。也就是说你本地跑通ci:validate加上两个冒烟脚本基本等同于 CI 全绿。2. 部署工作流 deploy-site.yml见下一节。六、GitHub Pages 部署机制推送即上线部署工作流 deploy-site.yml 由两类事件触发push 到site-first分支且改动路径为site/**或registry/**——这就是推送即部署的来源workflow_dispatch——允许在 Actions 页面手动触发部署。流程分两个 jobbuild配置 Pages →npm ci安装依赖 →npm run build构建 → 将产物site/dist上传为 Pages 制品deploy依赖 build 成功后调用actions/deploy-pages将制品发布到 GitHub Pages。两个值得注意的工程细节权限最小化contents: readpages: write部署不需要读取以外的仓库写权限串行化部署工作流设置了concurrency.group: pages且cancel-in-progress: false。注释解释了原因——取消运行并不能中止服务端已创建的 Pages 部署强行取消会导致下一次部署报 in progress deployment排队queueing则保证每次部署依次完成。⏱️ 提示正因为部署是排队串行的短时间内连续推送多次后几次部署会排队等待。本地开发阶段请用npm run preview预览不要依赖线上站点确认效果。七、贡献规范新手提交指南以下要点整理自 CONTRIBUTING.md按顺序做即可基于site-first分支开发这是站点、注册表与安装器流程的主分支控制改动范围保持小步提交site/内的改动需遵循既有设计语言不要在site-first上重新引入 mirror 时期的脚本或 submodule 流程提交前本地验证并在 PR 描述中附上验证证据npm run ci:validate若改动了安装器行为再补跑第四节的两个冒烟测试写清楚的 commit 信息说明改动意图而不是只写 fix。涉及技能归属时可参考 ATTRIBUTIONS.md 中记录的各技能来源与许可。八、常见问题速查Q1为什么npm run build比astro build多干了一步根目录的 build 脚本package.json会先执行node scripts/build-slim-index.mjs为 AI 智能体生成轻量索引 site/public/index.slim.json再执行 Astro 构建。跳过这一步站点会缺少 agent 索引。Q2只想更新星数等元数据使用npm run refresh:stars它调用 scripts/refresh-stars.mjs。Q3校验报错untranslated summary.zh是什么意思注册表中某个技能的中文摘要和英文摘要完全一致说明没做真正的翻译需要补写 registry/skills.json 中对应的summary.zh。Q4本地站点和线上不一致优先检查是否直接用了site/内命令构建而漏掉了根目录的索引生成步骤统一从仓库根目录使用npm run build即可。到这里你已经掌握了 Academic Forge 的完整本地开发闭环装依赖 → 预览站点 → 复现 CI 校验 → 理解 Pages 部署 → 规范提交贡献。从本地一条npm run ci:validate到线上自动部署每一步都有对应的本地命令可以先行验证放心开始你的第一次贡献吧。【免费下载链接】AcademicForgeOne Forge, All Skills: A curated skill collection for academic writing and research. 点开即用按需配置的一站式学术研究skills平台。项目地址: https://gitcode.com/gh_mirrors/ac/AcademicForge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Academic Forge 本地开发与贡献完全指南：从站点预览到 CI 校验和 GitHub Pages 部署
Academic Forge 本地开发与贡献完全指南从站点预览到 CI 校验和 GitHub Pages 部署【免费下载链接】AcademicForgeOne Forge, All Skills: A curated skill collection for academic writing and research. 点开即用按需配置的一站式学术研究skills平台。项目地址: https://gitcode.com/gh_mirrors/ac/AcademicForgeAcademic Forge是面向 Claude Code / OpenCode / Codex 的学术技能Skill选配与安装平台用户在网页上勾选所需技能包一键生成安装命令即可在自己的项目中使用。这篇文章面向第一次接触本项目的开发者带你完整走一遍本地开发流程安装依赖、预览站点、跑通校验与测试、理解 CI 流水线最后了解 GitHub Pages 的自动部署机制。一、30 秒看懂项目结构在动手之前先花 30 秒建立整体认知后面的每一步你都会知道为什么改这里目录 / 文件作用site/Astro Tailwind 构建的选配站点源码registry/skills.json技能注册表站点和安装器共同的数据源scripts/注册表校验、索引构建、安装脚本skills/本地维护的技能包含 32 个 Claude Science 技能.github/workflows/CI 工作流校验与部署主分支是site-first所有站点、注册表与安装器相关的贡献都基于它进行详见 QUICKSTART.md 与 CONTRIBUTING.md。二、一键完成本地环境准备环境要求Node.js ≥ 22.12.0在 site/package.json 中声明了最低版本CI 使用的也是 22.12.0Git克隆仓库并安装依赖git clone https://gitcode.com/gh_mirrors/ac/AcademicForge cd AcademicForge npm run site:installsite:install是根目录 package.json 定义的快捷脚本实际等价于在site/目录内执行npm install。根目录本身不需要安装依赖所有构建、校验脚本都是零依赖的 Node 脚本。三、最快站点预览方法三步跑起本地站点在仓库根目录依次执行npm run build npm run previewbuild会先执行scripts/build-slim-index.mjs生成轻量索引文件即 site/public/index.slim.json 的来源再调用 Astro 构建静态站点preview启动本地静态服务器浏览器打开后即可看到线上同款站点。如果你希望边改边看可以直接用开发服务器npm run dev 一个小知识站点地址带/AcademicForge前缀是因为它在 site/astro.config.mjs 中配置了base: /AcademicForgeGitHub Pages 项目站点的子路径。本地preview同样会遵守该配置属于正常现象。四、本地复现 CI 校验提交前必跑命令本项目的 CI 核心就是一条命令npm run ci:validate。你可以在提交前本地完整复现 CI 的判定结果避免白等流水线。1. 注册表校验npm run validate:registry它执行 scripts/validate-registry.mjs逐条检查 registry/skills.json典型拦截规则包括skill id 重复install.method不是git-clone/sparse-checkout之一使用sparse-checkout但缺少install.sparse_path本地技能包scientific-visualization、claude-science 及其子技能声明的sparse_path在磁盘上不存在中英文摘要内容完全相同即summary.zh未真正翻译。校验通过的输出是Registry validation passed.任何一条规则不满足都会打印具体错误并以非零码退出。2. 站点与脚本单元测试npm run test它串联两组测试定义见 package.jsontest:site运行 site/src/lib/ 下的*.test.mjs覆盖分类、卡片选择、安装命令生成等站点逻辑test:scripts运行注册表校验器等脚本的测试。两者都基于 Node 内置的node --test运行器无需额外测试框架。3. 一次性全量校验等价于 CInpm run ci:validate该命令依次执行validate:registry→test→build与 CI 校验工作流中的关键步骤一一对应。4. 改动安装器时追加冒烟测试如果你修改了 scripts/forge-install.sh 或 scripts/forge-install.ps1CONTRIBUTING.md 要求额外运行本地安装器冒烟测试bash scripts/tests/forge-install-local-registry.sh pwsh -File scripts/tests/forge-install-local-registry.ps1另有 scripts/tests/forge-install-multiple-sparse-checkouts.sh 用于验证多技能 sparse-checkout 安装场景CI 也会执行它。五、理解 CI校验流水线在做什么项目的 CI 由两个独立工作流组成目录为 .github/workflows/。1. 校验工作流 validate.yml触发条件push 或 pull_request 指向site-first分支且改动路径命中registry/、scripts/、site/、skills/scientific-visualization/、skills/claude-science/或根目录package.json。流水线步骤检出代码并用 Node 22.12.0 初始化环境带 npm 缓存执行npm ci --prefix site安装站点依赖执行npm run ci:validate即上文的校验 测试 构建全量流程依次运行本地注册表安装冒烟测试与多 sparse-checkout 冒烟测试。也就是说你本地跑通ci:validate加上两个冒烟脚本基本等同于 CI 全绿。2. 部署工作流 deploy-site.yml见下一节。六、GitHub Pages 部署机制推送即上线部署工作流 deploy-site.yml 由两类事件触发push 到site-first分支且改动路径为site/**或registry/**——这就是推送即部署的来源workflow_dispatch——允许在 Actions 页面手动触发部署。流程分两个 jobbuild配置 Pages →npm ci安装依赖 →npm run build构建 → 将产物site/dist上传为 Pages 制品deploy依赖 build 成功后调用actions/deploy-pages将制品发布到 GitHub Pages。两个值得注意的工程细节权限最小化contents: readpages: write部署不需要读取以外的仓库写权限串行化部署工作流设置了concurrency.group: pages且cancel-in-progress: false。注释解释了原因——取消运行并不能中止服务端已创建的 Pages 部署强行取消会导致下一次部署报 in progress deployment排队queueing则保证每次部署依次完成。⏱️ 提示正因为部署是排队串行的短时间内连续推送多次后几次部署会排队等待。本地开发阶段请用npm run preview预览不要依赖线上站点确认效果。七、贡献规范新手提交指南以下要点整理自 CONTRIBUTING.md按顺序做即可基于site-first分支开发这是站点、注册表与安装器流程的主分支控制改动范围保持小步提交site/内的改动需遵循既有设计语言不要在site-first上重新引入 mirror 时期的脚本或 submodule 流程提交前本地验证并在 PR 描述中附上验证证据npm run ci:validate若改动了安装器行为再补跑第四节的两个冒烟测试写清楚的 commit 信息说明改动意图而不是只写 fix。涉及技能归属时可参考 ATTRIBUTIONS.md 中记录的各技能来源与许可。八、常见问题速查Q1为什么npm run build比astro build多干了一步根目录的 build 脚本package.json会先执行node scripts/build-slim-index.mjs为 AI 智能体生成轻量索引 site/public/index.slim.json再执行 Astro 构建。跳过这一步站点会缺少 agent 索引。Q2只想更新星数等元数据使用npm run refresh:stars它调用 scripts/refresh-stars.mjs。Q3校验报错untranslated summary.zh是什么意思注册表中某个技能的中文摘要和英文摘要完全一致说明没做真正的翻译需要补写 registry/skills.json 中对应的summary.zh。Q4本地站点和线上不一致优先检查是否直接用了site/内命令构建而漏掉了根目录的索引生成步骤统一从仓库根目录使用npm run build即可。到这里你已经掌握了 Academic Forge 的完整本地开发闭环装依赖 → 预览站点 → 复现 CI 校验 → 理解 Pages 部署 → 规范提交贡献。从本地一条npm run ci:validate到线上自动部署每一步都有对应的本地命令可以先行验证放心开始你的第一次贡献吧。【免费下载链接】AcademicForgeOne Forge, All Skills: A curated skill collection for academic writing and research. 点开即用按需配置的一站式学术研究skills平台。项目地址: https://gitcode.com/gh_mirrors/ac/AcademicForge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考