面向编码 Agent 的 al-folio v1.x 仓库协作指南从开发循环到 CI 门禁的完整工程实践【免费下载链接】al-folioA beautiful, simple, clean, and responsive Jekyll theme for academics项目地址: https://gitcode.com/GitHub_Trending/al/al-folio本指南以 al-folio 仓库根目录的 CLAUDE.md 为核心骨架结合 AGENTS.md、docs/ARCHITECTURE.md 与 docs/BOUNDARIES.md 三份权威文档系统讲解在 al-folio v1.x「薄启动器 插件 Gem」架构下编码 AgentClaude Code 等应遵循的开发循环、变更路由规则、静默失败模式、Docker 服务模型、CI 门禁与 Gem 版本固定策略。读完本文你将掌握这套仓库的完整工程化协作约定能够正确判断一个改动应落在启动器还是插件 Gem并熟练使用经过验证的命令集完成开发、构建、测试与升级审计。一、文档定位谁在指挥 Agent 工作CLAUDE.md 是仓库提供给 Claude Code 的引导文件但它的地位是**「面向 Claude 的补充说明」**真正的权威入口是它第一行AGENTS.md导入的 AGENTS.md。这份文件被明确标注为authoritative agent entry point负责定义四件事变更路由change routing你的改动该放在仓库的哪个位置Stop Sign哪些路径在启动器仓库中禁止出现三种无报错静默失败模式three silent failure modes最典型的「我改了但什么都没发生」的根因经过验证的命令集validated command set从依赖安装到 Docker 冒烟测试的完整命令序列。而跨越仓库的架构细节wrapper/tag/gem 委托表、特性门控、v1 配置契约、本地覆盖存放在 docs/ARCHITECTURE.md区域到 Gem 的归属表在 docs/BOUNDARIES.md。CLAUDE.md 的硬性要求是在编辑任何东西之前先读这三份文档并且「不重复陈述这三份文件中的事实而是链接过去」。这本身就是一条值得所有协作项目借鉴的文档组织原则——每个事实只存在于一个地方keep each fact in one place — link rather than restate。二、核心架构前提薄启动器而非主题要理解 CLAUDE.md 中的每一条命令和门禁必须先建立 v1.x 的架构心智模型al-folio v1.x 是一个薄的 Jekyll 启动器thin starter不是一个主题theme。这一论断在 docs/ARCHITECTURE.md 中有明确阐述仓库本身只拥有四类东西启动器拥有的内容具体位置启动器接线wiringGemfile、_config.yml、_data/featured_plugins.yml示例内容_pages、_posts、_projects、_news、_teachings、_books、_bibliography文档docs/跨插件集成测试与视觉对比测试test/integration_*.sh、test/visual/所有运行时内容——布局layouts、包含文件includes、Sass、Liquid 标签、过滤器、特性 JS——全部位于独立发布、独立版本化的 Gem 中核心是al_folio_core配套的还有al_folio_cv、al_folio_distill、al_search、al_charts、al_math、al_comments、al_analytics、al_rtl等一整套功能 Gem。这些 Gem 在 Gemfile 的group :al_folio_plugins中逐一以精确版本固定并在 _config.yml 的plugins:列表中一一对应列出。因此文档反复强调最常见的错误就是在启动器里编辑运行时内容。如果一个改动涉及 layout、include、tag、filter 或任何特性行为它属于拥有它的 Gem而不是这个仓库。2.1 变更路由表左列是改动右列是去向AGENTS.md 提供了一张精确的路由表写作或评审 PR 之前应首先对照你的改动应该放在依赖固定、插件激活、特性开关本仓库Gemfile和_config.yml两者必须同时改示例/演示内容、参考文献、数据文件本仓库_pages、_posts、_projects、_news、_teachings、_books、_data文档本仓库docs/长文或 AGENTS.mdAgent 规则跨插件集成测试、视觉对比测试本仓库test/integration_*.sh、test/visual/插件目录元数据本仓库_data/featured_plugins.ymllayout、include 或 Sass 片段所属 Gem——从al_folio_core开始Liquid 标签/过滤器或标签渲染的内容注册该标签的 Gem——见 委托表特性行为搜索、数学、图表、评论、cookies、图标、CV、distill、分析、图片、newsletter、引用该特性的 Gem——见 docs/BOUNDARIES.mdGem 行为的组件/单元测试所属 Gem而不是这里没有现有归属者的新特性先开插件提案 issue再建独立插件仓库2.2 Stop Sign启动器中不得出现的路径如果改动会在本仓库创建以下任何路径它必须归入 Gem而非启动器_layouts/ _includes/ _sass/ _scripts/ assets/tailwind/ tailwind.config.js assets/webfonts/这条边界由npm run lint:style-contract即 test/style_contract.js自动化强制一旦上述路径存在CI 即失败并且该脚本还会拒绝build:css/build:tailwind这类 npm 脚本——也就是说不允许在启动器内引入本地 Tailwind 或 CSS 构建管线。需要强调的是这条限制只针对启动器仓库本身由模板创建的用户站点合法地可以在自己的仓库中覆盖shadowGem 拥有的文件二者的规则恰好相反详见 docs/ARCHITECTURE.md。三、三种无报错的静默失败模式AGENTS.md 与 docs/ARCHITECTURE.md 把「我改了但什么都没发生」这类问题的根因归纳为三条其中任何一条都不会产生构建错误因此排查时必须主动核对。3.1 特性在缺少 Gem 或关闭开关时静默失败特性门控是两层的只有两层同时满足特性才会渲染站点级配置开关位于_config.ymlsearch_enabled、enable_math、enable_cookie_consent、enable_darkmode、al_folio.features.cv.enabled、al_folio.features.distill.enabled以及analytics:下的各 provider ID页面级 front matterimages:、tikzjax、chart.*、mermaid.*、giscus_comments、layout: distill、layout: cv。al_folio_core在_includes/plugins/*.liquid中提供薄包装器调用兄弟 Gem 定义的自定义 Liquid 标签。当拥有该特性的 Gem 不在插件列表里或开关处于关闭状态时标签输出空字符串——没有警告、没有缺失标签错误、没有任何视觉占位符特性就是「不在那里」。排查「特性不工作」时按以下顺序检查Gem 是否同时出现在Gemfile和_config.yml的plugins:列表中见下文 3.2站点级开关是否打开页面 front matter 是否选择启用third_party_libraries中对应条目及其 SRI 哈希是否存在3.2Gemfile与_config.yml是两份必须一致的清单插件激活需要在两个文件里做两处编辑Gemfile 的group :al_folio_plugins——固定版本的依赖声明例如gem al_folio_core, 1.0.15_config.yml 的plugins:列表——Jekyll 的激活入口。只出现在其中一个文件里的 Gem 是无效的只在Gemfile中Jekyll 永远不会加载它只在plugins:中Bundler 永远不会安装它。添加或移除插件都必须同时编辑两个文件。另外要注意命名拼写差异仓库目录用连字符al-folio-coreGem 与插件 ID 用下划线al_folio_core。3.3 本仓库的有效 baseurl 是/al-folio演示站点以项目页project page形式发布因此_config.yml中已经设置了baseurl: /al-folio。普通构建会自动带上它——deploy.yml、broken-links-site.yml和axe.yml都直接运行无参的bundle exec jekyll build。显式传--baseurl /al-folio是冗余但无害的命令集之所以写全是为了让服务路径毫无歧义bundle exec jekyll build --baseurl /al-folio bundle exec jekyll serve # 访问 http://localhost:4000/al-folio/ 注意路径真正会把站点弄坏的是把 baseurl 清空用空 baseurl 构建所有资源与内部链接都会多算一层路径表现为「构建成功但页面完全没有样式」。Docker 入口点同样在/al-folio下服务。在你自己创建的站点中情况不同个人/组织站点username.github.io必须保持baseurl为空但存在项目站点则设置baseurl: /project-name/。四、Wrapper→标签→Gem 委托运行时如何连接CLAUDE.md 明确指出跨仓库架构细节wrapper/tag/gem 委托表等在 docs/ARCHITECTURE.md 中。该表揭示了一个关键设计al_folio_core是枢纽——_config.yml设置theme: al_folio_coreGem 提供所有基础_layouts/*.liquid与_includes/*.liquid、基础主题 JS/CSS、details与file_exists标签以及hideCustomBibtex与remove_accents过滤器。它的_includes/plugins/*.liquid包装器将请求委托给兄弟 Gem 拥有的标签包装器 / 调用点Liquid 标签所属 Gem搜索资源al_search_assetsal_searchCmd-K ninja-keys 命令面板索引在构建时从内容生成评论al_commentsal_commentsGiscus Disqusfront matter 门控Cookie 横幅al_cookie_styles/al_cookie_scriptsal_cookie通过 consent-mode 门控分析脚本图标linkal_icons_stylesal_iconsFontAwesome/Academicons/Scholar IconsCDN 加载分析al_analytics_scriptsal_analyticsGA/Cronitor/Pirsch/OpenPanel数学al_math_styles/al_math_scriptsal_mathMathJax、pseudocode.js、TikZJax图表al_charts_scriptsal_chartsMermaid/Chart.js/ECharts/Plotly/Vega/Leaflet/diff2html图像工具al_img_tools_styles/al_img_tools_scriptsal_img_toolszoom、lightbox、sliders、galleriesNewsletteral_newsletter_form/al_newsletter_scriptsal_newsletterLoops.so 注册表单html属性al_rtl_html_attrs/al_rtl_stylesal_rtlRTL 脚本页面langal_rtl.langs可覆盖语言集合邮箱地址al_email_protect_styles/al_email_protect_scriptsal_email_protect站点protect_email: truemarimo notebookal_marimo_styles/al_marimo_scripts/al_marimo_embedal_marimo页面marimo: truelayout: cval_folio_cv_renderal_folio_cvRenderCV YAML JSONResumelayout: distillal_folio_distill_renderal_folio_distill内置、哈希固定的 distillpub 运行时引用徽章google_scholar_citations/inspirehep_citationsal_citations外部文章生成器无标签al_ext_postsRSS/URL 摄取为合成文章遗留 Bootstrap 行为可选资源al_folio_bootstrap_compat升级/审计 CLIbundle exec al-folio …al_folio_upgrade4.1 特性 Gem 如何交付资源大多数特性 Gem 是 JekyllGenerator只在特性启用时于构建期注入其 JS/CSS 静态文件。由此带来三个值得知道的后果这些资源不提交到本仓库全新 checkout 的assets/下找不到它们只有启用了对应特性后它们才会出现在_site/中多个资源从带 Subresource IntegritySRI哈希的固定 CDN URL 加载哈希从_config.yml的third_party_libraries:块读取。升级某个库的版本意味着要同步升级同一块中的integrity哈希不要为了「修复」缺失资源而把图标字体或运行时 JS 反哺进启动器路径——那是上面第 3.1 节静默门控的症状而不是打包缺陷。五、v1 配置契约与本地覆盖5.1 契约键不可删除_config.yml必须保留al_folio契约键见 docs/ARCHITECTURE.mdal_folio.api_version: 1al_folio.style_engine: tailwindal_folio.tailwind.{version,css_entry,preflight}al_folio.distill.{engine,source}这些键被双重强制一是al_folio_core的:after_init钩子在构建期发出警告二是bundle exec al-folio upgrade audit将其作为阻断性发现项CI 通过upgrade-check.yml运行它。当前仓库的实际取值可在 _config.yml 中核对例如style_engine: tailwind、tailwind.version: 4.1.18、tailwind.preflight: false、distill.engine: distillpub-template。5.2 本地覆盖你的站点与本仓库规则相反这两类情况的规则恰好相反混淆是反复出现的困惑来源在你自己创建的站点中由模板生成的仓库本地覆盖完全受支持。你可以在仓库中添加同名路径来 shadow 任意 Gem 拥有的文件——_layouts/bib.liquid、_includes/repository/repo.liquid、_sass/_variables.scss等等你的副本优先级高于 Gem 的。跟踪它们以便未来的 Gem 更新能标记漂移bundle exec al-folio upgrade overrides audit bundle exec al-folio upgrade overrides diff path bundle exec al-folio upgrade overrides accept pathoverrides audit会在.al-folio-overrides.yml中记录所属 Gem、版本以及上游/本地 SHA256。提交该文件。当后续bundle update改变了上游文件时audit 会把你的覆盖标记为过期stale。能让所有人受益的修复应移植到所属 Gem而不是保留为本地覆盖。在启动器仓库本身本仓库上述目录不允许存在npm run lint:style-contract会在存在_includes/、_layouts/、_sass/、_scripts/、assets/tailwind/、tailwind.config.js、assets/webfonts/或图标字体产物时令构建失败。这是对薄启动器边界的自动化强制适用于对 al-folio 的贡献而不适用于用户站点。文档还特别给维护者留了一个已知待决问题open maintainer decisiontest/style_contract.js与unit-tests.yml会随模板分发到每个站点因此用户若在其 fork 中添加完全合法的本地覆盖也会看到启动器自身的契约检查失败。六、Bootstrap 兼容可选且限时al_folio.compat.bootstrap.enabled: true默认false激活al_folio_bootstrap_compat恢复 Tailwind 优先 v1 核心上的遗留data-toggle与 Bootstrap 类行为。其时间线明确写死在_config.yml的al_folio.compat.bootstrap块中支持至v1.2在v1.3弃用在v2.0移除因此应在限时窗口内把内容迁离 Bootstrap 标记。七、日常开发循环Daily Dev LoopCLAUDE.md 给出的是最小日常循环逐条解释如下bundle install # 安装 Ruby Gem bundle exec jekyll serve # 开发服务器 → http://localhost:4000/al-folio/ 注意 baseurl bundle exec jekyll build --baseurl /al-folio # 生产风格构建到 _site/ bash test/integration_distill.sh # 运行一个集成测试test/ 下共有七个 npm run test:visual:update # 有意变更 UI 后刷新 Playwright 快照 bundle exec al-folio upgrade apply --safe # 确定性 codemodsfont-weight-* → font-*、remote→local URL bundle exec al-folio upgrade overrides diff path # 之后用 overrides accept path 确认一个覆盖其中值得注意的细节bundle exec jekyll serve的访问路径是http://localhost:4000/al-folio/因为 baseurl 是/al-folio集成测试共有七个test/下以integration_*.sh命名integration_distill.sh只是其中之一upgrade apply --safe是确定性 codemod把font-weight-*重命名为font-*、把 remote URL 转成本地 URLupgrade overrides diff path用于查看本地覆盖与上游的差异确认后使用overrides accept path记录。八、可选工具链按需安装避免误伤8.1 Jupyter 文章bin/setup-python-deps只安装jupyter和nbconvert通过pip --user --break-system-packages供jekyll-jupyter-notebook使用。它不读取requirements.txt。缺少jupyter-nbconvert时是 warn-and-continue警告后继续notebook 渲染被跳过构建不会失败。8.2 其余 Python 依赖requirements.txt 是更完整的清单必须单独安装python3 -m pip install -r requirements.txt其中包括CV 渲染用的rendercv[full]、bin/update_scholar_citations.py依赖的scholarly以及nbconvert和pyyaml。8.3 响应式图片imagemagick.enabled: true当前仓库中确实为true见 _config.yml需要 ImageMagick 的convert命令在PATH上。启用前可先运行convert -version验证。8.4 手动部署bin/deploy是手动gh-pages构建 purgecss force-push 的路径正常情况下由 CI 部署。purgecss不是 devDependency——需要npm install -g purgecss全局安装。从 bin/deploy 的源码可见其完整流程默认从main分支切换到gh-pages分支、以JEKYLL_ENVproduction构建、用purgecss -c purgecss.config.js清理未使用的 CSS、把_site/*提升到分支根、写入.nojekyll后强推部署分支支持-u/--user、-s/--src、-d/--deploy、--verbose、--no-push等参数且会在开始前检查未提交改动与未跟踪文件。九、Docker 服务模型v1 特有CLAUDE.md 描述的 v1 Docker 模型在 bin/entry_point.sh、Dockerfile 与 docker-compose.yml 中有完整的源码佐证docker compose up -d将仓库 bind-mount 到容器的/srv/jekyll并运行bin/entry_point.sh该脚本以--force_polling --destination /tmp/_site启动 Jekyll serve。构建输出刻意输出到容器本地/tmp/_site而不是 bind-mount 的_site——因为把_site跨宿主 bind-mount 写回曾导致写入死锁。这是本模型最反直觉的一点也是必须遵守的设计决策。此外容器通过inotifywait监听_config.yml的改动modify,move,create,delete事件发生变化时强杀 Jekyll 进程并重启——因为--watch不会热重载配置文件的编辑。入口脚本还做了两件事一是管理Gemfile.lock若被 git 跟踪则git restore还原否则删除二是bundle check不通过时自动bundle install --jobs 4 --retry 3。用 baseurl 验证服务是否正常curl -fsS http://127.0.0.1:8080/al-folio/docker-compose.yml 还暴露了 35729 端口livereload而 docker-compose-slim.yml 则直接拉取预构建的:slim镜像而不是本地构建。若遇到.jekyll-cache权限问题Permission denied rb_sysopen - /srv/jekyll/.jekyll-cache/.gitignoreDockerfile 顶部注释提供了非 root 用户的解法设置GROUPID/GROUPNAME/USERID/USERNAME构建参数并在 compose 中填入id -g、id -gn、id -u、echo $USER的输出。十、CI 门禁与样式契约Style Contract10.1 样式契约薄启动器边界的自动化执行npm run lint:style-contracttest/style_contract.js是薄启动器边界的自动化强制手段违反即 CI 失败。从源码看它断言的内容包括package.json不得定义build:css/build:tailwind/build:tailwind:watch脚本_config.yml必须保持theme: al_folio_core且plugins:必须包含al_folio_core、al_folio_distill、al_cookie、al_icons、al_maththird_party_libraries必须定义fontawesome、academicons、scholar-icons且带 SRI 哈希integrity.css以sha开头tikzjax与tocbot条目必须存在Gemfile中al_math必须固定到某个已发布版本 x.y.z禁止git 分支固定gem al_math, :git ...本仓库不得拥有_includes、_layouts、_sass、_scripts、assets/tailwind、tailwind.config.js、assets/webfonts以及assets/fonts/academicons.woff、academicons.ttf、scholar-icons.woff、scholar-icons.ttf等图标字体产物test/visual、test/integration_plugin_toggles.sh、test/integration_distill.sh三个路径必须存在。关于al_math的检查脚本注释点明了设计意图只要求固定到某个已发布版本而不硬编码具体版本号——硬编码数字会让每次例行版本升级都先撞一次契约检查成为升级的绊线tripwire而非边界的守卫。10.2 其他门禁unit-tests.yml——样式契约加全部七个test/integration_*.sh脚本comments、plugin_toggles、distill、bootstrap_compat、upgrade_cli、css_minify、new_pluginsvisual-regression.yml——Playwright 在 chromium webkit 上运行把候选构建与通过BASELINE_URL服务在:4100的v0.16.3基线工作树做 diff相关配置见 test/visual/playwright.config.jsupgrade-check.yml——运行bundle exec al-folio upgrade auditprettier.yml——Prettier shopify/prettier-plugin-liquidprintWidth: 150。推送前运行npm run lint:prettiernpx prettier . --write可自动修复update-tocs.yml——重新生成根目录与docs/下 Markdown 文件的!--ts--…!--te--目录块。如果你新增或重命名了标题预期main上会出现一个后续自动提交。十一、Gem 版本固定以 Gemfile 为准Gemfile 在group :al_folio_plugins中把每个al-*Gem 固定到精确的已发布版本_config.yml的plugins:中列出相同的 Gem。CLAUDE.md 特意强调以 Gemfile 中当前的固定版本为准不要轻信任何散落在正文中的版本号——包括本文档内的。要在本站点测试某个 Gem 的修复可以把Gemfile指向兄弟 checkoutpath:、git:或branch:后重新安装完整流程见 docs/ARCHITECTURE.mdgem al_folio_core, path: ../al-folio-core # 或 git: / branch:bundle install bundle exec jekyll build --baseurl /al-folio提交前必须把Gemfile还原为固定的已发布版本——Gemfile 中的固定版本是启动器接线的一部分且test/style_contract.js会断言其中一部分如al_math的精确版本固定。十二、经过验证的完整本地命令集AGENTS.md 给出了从仓库根目录按顺序执行的完整验证命令集作为日常循环的补充是本地全量验证的权威清单bundle install npm ci npm run lint:prettier npm run lint:style-contract bundle exec jekyll build --baseurl /al-folio bash test/integration_comments.sh bash test/integration_plugin_toggles.sh bash test/integration_distill.sh bash test/integration_bootstrap_compat.sh bash test/integration_upgrade_cli.sh bash test/integration_css_minify.sh bash test/integration_new_plugins.sh npx playwright install chromium webkit npm run test:visual bundle exec al-folio upgrade audit bundle exec al-folio upgrade overrides audit bundle exec al-folio upgrade report docker compose up -d curl -fsS http://127.0.0.1:8080/al-folio/ /dev/null docker compose logs --tail80 docker compose down要点回顾全部七个test/integration_*.sh脚本都由unit-tests.yml门控只跑与你改动相关的即可Docker 部分验证的是 v1 模型使用/srv/jekyll/bin/entry_point.sh从容器本地/tmp/_site服务以避免宿主 bind-mount 写死锁视觉测试前需先npx playwright install chromium webkit安装两个浏览器运行时。十三、开 PR 之前的检查清单综合 CLAUDE.md 与 AGENTS.md提交 PR 前应逐项确认启动器工作留在本仓库运行时行为路由到所属插件仓库——对照路由表与 Stop Sign 再检查一遍改动归属运行npm run lint:prettierPrettier shopify/prettier-plugin-liquidprintWidth: 150npx prettier . --write可修复格式保持文档与 v1 归属一致每个事实只存在于一个地方——链接而非复述link rather than restate如果创建或保留了插件拥有文件的本地覆盖运行bundle exec al-folio upgrade overrides audit并在审阅后提交.al-folio-overrides.yml。十四、进一步阅读仓库内继续深入阅读的入口均已在文中涉及此处汇总AGENTS.md——Agent 的权威入口路由表、Stop Sign、静默失败模式、验证命令集docs/ARCHITECTURE.md——启动器与 Gem 如何连接、静默失败模式详解、v1 配置契约、本地覆盖docs/BOUNDARIES.md——权威的区域到 Gem 归属表与 PR 分流手册docs/CONTRIBUTING.md——贡献者工作流与 Agent 工具docs/README.md——全部用户与维护者指南索引docs/FAQ.md 与 docs/CUSTOMIZE.md——常见问题如 baseurl 部署异常、遗留 Bootstrap 页面处理与站点定制细节。结语CLAUDE.md 及其背后的三份权威文档共同勾勒出一套对「人机协作」高度友好的工程约定薄启动器边界靠 test/style_contract.js 自动化守卫运行时行为靠 wrapper→标签→Gem 委托表清晰归属版本与配置契约靠 Gemfile 与 _config.yml 的双清单一致性和al-folio upgrade审计双重保障Docker 服务模型则针对 bind-mount 死锁、配置热加载缺失等真实痛点给出了具体解法。对于任何要在 al-folio v1.x 上工作的 Agent 或开发者先把「变更路由 → Stop Sign → 三种静默失败 → 验证命令集」这条链路走通就能避开绝大多数「改了没生效」的陷阱让改动以正确的方式落到正确的位置。【免费下载链接】al-folioA beautiful, simple, clean, and responsive Jekyll theme for academics项目地址: https://gitcode.com/GitHub_Trending/al/al-folio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考