AGENTS.md

This file provides guidance to ALL coding agent when working with code in this repository.

项目结构

这是一个基于 Jekyll 的静态网站，用作学术个人主页。

• 核心页面: 用户可见的主要页面位于 _pages/ 目录下。
• 博客文章: 存放在 _posts/ 目录，文件名必须严格遵循 YYYY-MM-DD-title.md 格式以确保正确排序。
• 布局与组件: _layouts/ 定义页面整体结构；_includes/ 存放头部、底部等可复用代码片段。
• 数据驱动: _data/ 目录包含驱动网站内容的 YAML 文件（如 projects.yml, publications.yml）。修改列表类内容时，请优先修改数据文件，严禁在 HTML 模板中硬编码。
• 样式: SCSS 文件位于 _sass/。静态资源（图片、JS）分别在 images/ 和 assets/。
• 配置: _config.yml 是核心配置文件，控制全站设置、导航菜单和 SEO 参数。
• 自动化工具:
  • google_scholar_crawler/: 包含 main.py，用于抓取 Google Scholar 引用数据。
  • updateBlogs.py: 用于在本地刷新博客元数据的 Python 脚本。

常用开发命令

• 安装依赖: Running bundle install 安装 Ruby 依赖。
• 启动开发服务器: Running bash run_server.sh
  • 实际执行: bundle exec jekyll liveserve
  • 访问地址: http://127.0.0.1:4000
  • 特性: 支持热重载，修改后自动刷新。
• 构建生产版本: Running bundle exec jekyll build
  • 重要: 提交代码前必须运行此命令，确保构建无报错。
• 健康检查: Running bundle exec jekyll doctor
  • 用于检查配置文件错误或缺失的依赖。
• 更新学术引用数据: Running python3 google_scholar_crawler/main.py
  • 依赖: 需要设置环境变量 GOOGLE_SCHOLAR_ID。

外部服务集成与索引

本项目集成了多个第三方服务以提供统计、搜索索引和评论功能。相关配置主要位于 _config.yml。

• 搜索引擎索引 (SEO):
  • Google / Bing: 验证代码配置在 _config.yml 的 google_site_verification 和 bing_site_verification。
  • Sitemap: 自动生成，使用了 jekyll-sitemap 插件。
  • Google Analytics: ID 配置为 google_analytics_id。
• 评论系统 (Comments):
  • 方案: 使用 Valine (基于 LeanCloud)。
  • 配置: 在 _config.yml 的 valine 字段下。包含 appid 和 appkey。
  • 注意: Valine 是客户端渲染，Key 暴露在前端是预期的，但请勿在其中存储敏感权限过高的 Key（应限制 LeanCloud 权限）。
• 访问统计 (Visitor Stats):
  • 方案: 使用 Firebase Realtime Database。
  • 配置: 在 _config.yml 的 firebase 字段下 (apiKey, authDomain, etc.)。
• 个人与社交账号:
  • 配置: _config.yml 中的 author 部分包含所有社交媒体链接（如 GitHub, Zhihu, Twitter）。修改此处即可全局更新。

编码与开发规范

• 缩进风格: Liquid, HTML, SCSS 统一使用 2 个空格缩进。
• 命名约定:
  • SCSS 变量: camelCase (驼峰式)
  • CSS 类名: kebab-case (短横线连接)
  • Front Matter 键名: snake_case (下划线连接)
• 代码组织:
  • 尽量保持 Markdown 的纯粹性，除非为了特定的布局结构，否则避免混用内联 HTML。
  • 严格遵循内容（Markdown/_data）与表现（Layouts/CSS）分离的原则。

部署与工作流注意事项

• 安全隐私: 所有 API 密钥（如 Firebase配置, Google Scholar ID）必须存储在 GitHub Secrets 中，绝对禁止硬编码在源码中提交。
• Git 提交规范:
  • 使用简洁的英文祈使句。
  • 格式参考: feat: add new paper, fix: navigation bug, docs: update readme.
• 测试指南:
  • 项目没有自动化单元测试。
  • 务必运行 bundle exec jekyll build --trace 排查构建错误。
  • 提交前需手动从浏览器验证主页、项目页 (/projects) 和出版物页 (/publications) 的显示效果。
• 配置生效: 修改 _config.yml 文件后，必须重启开发服务器才能生效。