面向编码 Agent 的 al-folio v1.x 仓库协作指南：从开发循环到 CI 门禁的完整工程实践

面向编码 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」架构下，编码 Agent（Claude 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 中有明确阐述，仓库本身只拥有四类东西：

启动器拥有的内容	具体位置
启动器接线（wiring）	Gemfile、_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.md（Agent 规则）
跨插件集成测试、视觉对比测试	本仓库：test/integration_*.sh、test/visual/
插件目录元数据	本仓库：_data/featured_plugins.yml
layout、include 或 Sass 片段	所属 Gem——从al_folio_core开始
Liquid 标签/过滤器，或标签渲染的内容	注册该标签的 Gem——见 委托表
特性行为（搜索、数学、图表、评论、cookies、图标、CV、distill、分析、图片、newsletter、引用）	该特性的 Gem——见 docs/BOUNDARIES.md
Gem 行为的组件/单元测试	所属 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 构建管线。需要强调的是，这条限制只针对启动器仓库本身；由模板创建的用户站点合法地可以在自己的仓库中覆盖（shadow）Gem 拥有的文件，二者的规则恰好相反，详见 docs/ARCHITECTURE.md。

三、三种无报错的静默失败模式

AGENTS.md 与 docs/ARCHITECTURE.md 把「我改了但什么都没发生」这类问题的根因归纳为三条，其中任何一条都不会产生构建错误，因此排查时必须主动核对。

3.1 特性在缺少 Gem 或关闭开关时静默失败

特性门控是两层的，只有两层同时满足，特性才会渲染：

• 站点级配置开关（位于_config.yml）：search_enabled、enable_math、enable_cookie_consent、enable_darkmode、al_folio.features.cv.enabled、al_folio.features.distill.enabled，以及analytics:下的各 provider ID；
• 页面级 front matter：images:、tikzjax、chart.*、mermaid.*、giscus_comments、layout: distill、layout: cv。

al_folio_core在_includes/plugins/*.liquid中提供薄包装器，调用兄弟 Gem 定义的自定义 Liquid 标签。当拥有该特性的 Gem 不在插件列表里，或开关处于关闭状态时，标签输出空字符串——没有警告、没有缺失标签错误、没有任何视觉占位符，特性就是「不在那里」。

排查「特性不工作」时，按以下顺序检查：

1. Gem 是否同时出现在Gemfile和_config.yml的plugins:列表中？（见下文 3.2）
2. 站点级开关是否打开？
3. 页面 front matter 是否选择启用？
4. 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-core），Gem 与插件 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_core，Gem 提供所有基础_layouts/*.liquid与_includes/*.liquid、基础主题 JS/CSS、details与file_exists标签，以及hideCustomBibtex与remove_accents过滤器。它的_includes/plugins/*.liquid包装器将请求委托给兄弟 Gem 拥有的标签：

包装器 / 调用点	Liquid 标签	所属 Gem
搜索资源	al_search_assets	al_search（Cmd-K ninja-keys 命令面板，索引在构建时从内容生成）
评论	al_comments	al_comments（Giscus + Disqus，front matter 门控）
Cookie 横幅	al_cookie_styles/al_cookie_scripts	al_cookie（通过 consent-mode 门控分析脚本）
图标<link>	al_icons_styles	al_icons（FontAwesome/Academicons/Scholar Icons，CDN 加载）
分析	al_analytics_scripts	al_analytics（GA/Cronitor/Pirsch/OpenPanel）
数学	al_math_styles/al_math_scripts	al_math（MathJax、pseudocode.js、TikZJax）
图表	al_charts_scripts	al_charts（Mermaid/Chart.js/ECharts/Plotly/Vega/Leaflet/diff2html）
图像工具	al_img_tools_styles/al_img_tools_scripts	al_img_tools（zoom、lightbox、sliders、galleries）
Newsletter	al_newsletter_form/al_newsletter_scripts	al_newsletter（Loops.so 注册表单）
<html>属性	al_rtl_html_attrs/al_rtl_styles	al_rtl（RTL 脚本页面lang；al_rtl.langs可覆盖语言集合）
邮箱地址	al_email_protect_styles/al_email_protect_scripts	al_email_protect（站点protect_email: true）
marimo notebook	al_marimo_styles/al_marimo_scripts/al_marimo_embed	al_marimo（页面marimo: true）
layout: cv	al_folio_cv_render	al_folio_cv（RenderCV YAML + JSONResume）
layout: distill	al_folio_distill_render	al_folio_distill（内置、哈希固定的 distillpub 运行时）
引用徽章	google_scholar_citations/inspirehep_citations	al_citations
外部文章	（生成器，无标签）	al_ext_posts（RSS/URL 摄取为合成文章）
遗留 Bootstrap 行为	（可选资源）	al_folio_bootstrap_compat
升级/审计 CLI	bundle exec al-folio …	al_folio_upgrade

4.1 特性 Gem 如何交付资源

大多数特性 Gem 是 JekyllGenerator，只在特性启用时于构建期注入其 JS/CSS 静态文件。由此带来三个值得知道的后果：

• 这些资源不提交到本仓库；全新 checkout 的assets/下找不到它们，只有启用了对应特性后，它们才会出现在_site/中；
• 多个资源从带 Subresource Integrity（SRI）哈希的固定 CDN URL 加载，哈希从_config.yml的third_party_libraries:块读取。升级某个库的版本，意味着要同步升级同一块中的integrity哈希；
• 不要为了「修复」缺失资源而把图标字体或运行时 JS 反哺进启动器路径——那是上面第 3.1 节静默门控的症状，而不是打包缺陷。

五、v1 配置契约与本地覆盖

5.1 契约键不可删除

_config.yml必须保留al_folio契约键（见 docs/ARCHITECTURE.md）：

• al_folio.api_version: 1
• al_folio.style_engine: tailwind
• al_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 <path>

overrides 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 decision）：test/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 Loop）

CLAUDE.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 # 确定性 codemods（font-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 转成本地 URL；
• upgrade 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_ENV=production构建、用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/.gitignore），Dockerfile 顶部注释提供了非 root 用户的解法（设置GROUPID/GROUPNAME/USERID/USERNAME构建参数并在 compose 中填入id -g、id -gn、id -u、echo $USER的输出）。

十、CI 门禁与样式契约（Style Contract）

10.1 样式契约：薄启动器边界的自动化执行

npm run lint:style-contract（test/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_math；
• third_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_plugins）；
• visual-regression.yml——Playwright 在 chromium + webkit 上运行，把候选构建与通过BASELINE_URL服务在:4100的v0.16.3基线工作树做 diff（相关配置见 test/visual/playwright.config.js）；
• upgrade-check.yml——运行bundle exec al-folio upgrade audit；
• prettier.yml——Prettier +@shopify/prettier-plugin-liquid，printWidth: 150。推送前运行npm run lint:prettier；npx 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指向兄弟 checkout（path:、git:或branch:）后重新安装，完整流程见 docs/ARCHITECTURE.md：

gem "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 --tail=80 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 前应逐项确认：

1. 启动器工作留在本仓库，运行时行为路由到所属插件仓库——对照路由表与 Stop Sign 再检查一遍改动归属；
2. 运行npm run lint:prettier（Prettier +@shopify/prettier-plugin-liquid，printWidth: 150），npx prettier . --write可修复格式；
3. 保持文档与 v1 归属一致，每个事实只存在于一个地方——链接而非复述（link rather than restate）；
4. 如果创建或保留了插件拥有文件的本地覆盖，运行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