MapleInori.github.io

Imported from MapleInori/MapleInori.github.io (AGENTS.md). Install upstream with npx skills add MapleInori/MapleInori.github.io. Copyright stays with the author.

AGENTS.md

可根据情况自行决定是否调整该文档。

项目定位

本仓库是一个基于 Jekyll 的个人 GitHub Pages 站点。协作时优先保证两件事：

• 站点本身稳定可用
• 作者的个人文章与资料保持原样，除非用户明确要求修改

工作原则

• 优先做小而明确的改动，避免无关重构。
• 保持现有站点风格、目录结构和主题约定。
• 未经明确要求，不批量修改个人文章、学习笔记或配图。
• 涉及构建、布局、样式、脚本或配置时，结束前说明是否做过验证；如果没验证，也要明确写出。

GitHub Pages 兼容注意

• 本仓库最终运行在 GitHub Pages 自带的 Jekyll 环境上，协作时优先兼容 GitHub Pages 的旧版 Jekyll、Liquid、Sass，而不是只按本地编辑器或新语法习惯编写。
• 这里要特别避开的有两类模板符号：
  • 一类是“双层花括号变量写法”，通常用于输出变量。
  • 一类是“花括号加百分号标签写法”，通常用于 include、if、for 这类模板标签。
• 问题出现的具体情况是：GitHub Pages 会先解析 Liquid，再渲染 Markdown。只要这些符号出现在 AGENTS.md、项目修改记录、CHANGELOG.md 这类说明文档正文里，即使只是举例，也可能被当成真实模板语法执行，进而导致构建报错。
• 因此在说明文档中记录这类问题时，一律使用中文名称描述，不再直接写出这些符号本身，也不要再用实体转义去拼写它们。
• 如果必须在技术文档中展示真实 Liquid 代码，只能放进代码块，并在代码块外层使用 raw / endraw 包裹。
• _posts/ 文章正文里的代码块同样会被 GitHub Pages 先交给 Liquid 处理，不要因为内容在 Markdown 代码围栏里就认为它会跳过模板解析。Lua、Vue、Handlebars、Mustache 等示例如果出现连续两个左花括号，优先通过加空格、拆开示例或使用 raw / endraw 包裹来避免被解析。
• Lua 二维表或嵌套 table 示例中，外层左花括号后紧跟内层左花括号时，要写成中间带空格的形式；这不改变 Lua 语义，但能避免 GitHub Pages 把它误认为 Liquid 变量起始。
• 主题 SCSS 的 mixin 调用尽量沿用仓库现有写法；如果是 transition 这类主题封装过的 mixin，优先使用主题已经兼容的参数形式。
• _posts/image、_posts/2025Year/image 与 _posts/docs/UGUI/image 已加入构建排除列表，不应依赖 Jekyll 在发布时复制这些目录下的图片。
• 文章内相对图片路径 image/... 必须按 Markdown 源文件所在目录解析，不能按公开 URL 或 permalink 推断；带 docs/Unity/... permalink 的根层级文章仍应读取 _posts/image/...。
• 需要长期参与站点构建或页面渲染的公共资源，优先放在未被排除的站点资源目录中，例如 assets/。

哪些改动需要记录到 CHANGELOG.md

只要修改属于“GitHub Pages 项目本身”，就应在 CHANGELOG.md 顶部补充记录。包括但不限于：

• 站点配置与构建相关文件，如 _config.yml、Gemfile、package.json、脚本工具等
• 站点布局、组件、样式、脚本，如 _layouts/、_includes/、_sass/、assets/
• 导航、站点元数据、作者信息、公共数据，如 _data/
• 首页、归档页、关于页、404 页等站点级页面
• 会影响页面结构、交互、主题外观、部署方式、维护方式的改动

哪些改动不要求记录

以下内容默认不需要写入 CHANGELOG.md：

• _posts/ 下的个人文章、学习笔记、翻译、随笔
• docs 类个人资料和笔记内容
• 仅服务于某篇文章的图片、附件、示例素材
• 纯文字修订，如错别字、语句调整、内容补充

项目修改日志规则

• 站点项目本身发生改动时，除了在 CHANGELOG.md 记录摘要，还要在项目修改日志文章中记录详细过程。
• 项目修改日志只记录站点项目改动，不要求记录普通文档内容改动。
• 新的结构化项目修改日志统一存放在 _posts/docs/BlogChanges/。
• 现有日志文章 _posts/2025Year/2025-01-08-Blog修改.md 作为历史总记录保留，并与新日志共用同一个侧边栏导航。
• 从新文件开始，每篇结构化项目修改日志文章最多记录 10 次修改；达到 10 次后，新建下一篇继续记录。
• 每次修改记录都要以日期标题开头，推荐格式为 ## YYYY-MM-DD。
• 每次项目级修改后，仍然要在 CHANGELOG.md 同步写摘要，但项目修改日志正文不需要把 CHANGELOG.md 的同步更新单独写进“涉及文件”或改动说明里。
• 新的结构化项目修改记录页面默认应设置 home_exclude: true，避免出现在主页中间的文章列表里；历史文章 _posts/2025Year/2025-01-08-Blog修改.md 继续保留在主页列表中，不做隐藏。
• 每条记录都应写清楚：
  • 改了什么
  • 修改前是什么状态
  • 修改后变成什么样
  • 涉及哪些文件或页面
• 如果本次改动涉及 HTML、CSS 或 JavaScript，必须额外写清楚：
  • 修改了哪些脚本或页面文件
  • 修改前的代码
  • 修改后的代码
• 项目修改日志应接入与 UGUI 文档相同风格的多文档侧边栏导航，便于后续继续扩展。

主页导航约定

• 顶部导航只保留站点级入口，例如 About、Archive 和搜索功能。
• 主页右侧导航栏只展示“合集级入口”，例如 UGUI、Unity、Blog 修改 这类合集，不展开合集内部文章列表，也不展示零散单篇文章。
• 主页右侧每个合集入口只需要显示合集名字，点击后跳转到该合集的第一篇文章或该合集当前约定的入口页。
• 如果后续合集很多，优先继续扩展合集入口，不要把主页右侧导航做成长篇文章目录。

已知问题与处理经验

• AGENTS.md 属于仓库协作文档，不属于站点前台页面。它应继续保留在 _config.yml 的 exclude 中，避免参与 GitHub Pages 构建。
• 结构化项目修改日志、AGENTS.md、CHANGELOG.md 这类说明文档里，描述 Liquid 相关问题时优先用中文说“什么符号、什么情况”，不要在正文里再次写出符号本身。
• 首页模板当前应由 _layouts/home.html 直接继承 page，不要再改回 articles。否则很容易和手动插入的文章列表或分页形成重复结构。
• 首页中间栏必须同时具备“文章列表”和“分页”。paginator 组件只负责统计与页码，不负责渲染文章条目；如果只保留 paginator，首页就会只剩总数和翻页按钮。
• 首页当前使用 full_width: true，并通过 _sass/layout/_home.scss 控制三栏宽度。后续如果再次调整左右栏，优先先检查中间文章流是否被挤压，而不是只看左右卡片本身是否美观。
• 首页布局尺寸和响应式隐藏断点集中维护在 _sass/layout/_home.scss 顶部。后续优先调整这些变量，不要把新的固定尺寸散落到选择器中；响应式顺序应保持为“先平滑缩小左右栏，再隐藏左侧个人简介，最后隐藏右侧合集目录”。
• 带合集导航的文档页宽度变量集中维护在 _sass/layout/_page.scss 顶部。后续调整正文、左侧合集导航或右侧文章目录宽度时，先修改顶部变量，并检查小于 1024px 时左侧抽屉与右侧目录隐藏行为是否仍然正常。
• 左侧个人信息卡片依赖 _config.yml 中的 home_profile；如果头像、昵称或文案异常，优先检查这个配置和资源路径，而不是先改模板。
• 主页右侧目录使用独立的数据源 home-directory，不要再直接读取顶部 header 导航数据。顶部导航和主页右侧目录的职责必须分离。
• 主页右侧目录当前允许保留合集描述，但仍然只列合集入口，不展开合集内部文章。以后如果合集变多，优先继续保持“合集级目录”，不要回到单篇级目录。
• 结构化项目修改记录如果需要只保留在“修改记录合集”里，不显示在主页文章流中，应统一使用 home_exclude: true，不要再靠改日期或手动删列表来规避。
• _posts/image、_posts/2025Year/image 和 _posts/docs/UGUI/image 已被排除出构建。涉及站点公共资源时，优先放在 assets/ 等参与构建的目录。

Agent 自我迭代要求

• 每次连续修复同一块功能时，不能只做局部补丁；要在完成后回顾“真正原因是什么、哪条规则缺失、以后如何避免重复犯错”，并把结论写回本文件。
• 如果某次报错或布局问题已经通过排查定位出触发条件，后续再修改相关区域时，应主动按这个触发条件做一致性检查，而不是等用户再次反馈。
• 当临时方案和用户真实偏好不一致时，应尽快回退到更符合长期维护的版本，并把“为什么之前会偏掉、现在应以什么为准”写进规则。
• 更新规则时，优先写“判断标准”和“处理顺序”，不要只写单次修复动作；目标是让下一次修改能直接复用经验，而不是重新试错。
• 完成站点级修改后，除了同步更新项目修改日志和 CHANGELOG.md 摘要，还应检查当前改动是否让 AGENTS.md 变得过时；如果已经出现新的稳定经验，应及时补充。

边界处理

• 如果一次提交同时包含“站点项目改动”和“个人文档改动”，只需要记录站点项目改动部分。
• 如果不确定某个改动算不算“项目本身”，以“是否会影响站点运行、结构、样式、配置或维护”为判断标准。
• 判断不清时，宁可简短记录，也不要漏记站点级改动。

CHANGELOG.md 记录方式

• 新记录放在文件顶部，旧记录保留。
• 用日期作为入口即可，不要求严格版本号。
• 建议用简短项目符号说明“新增 / 调整 / 修复”。

示例：

## 2026-03-26

### Added

- 新增 Agent 协作规范，要求记录站点级改动

### Changed

- 调整首页导航结构