AGENTS.md

Notebook Repository Agent Guide

项目定位

• 类型：PhilFan 的个人知识库站点
• 站点框架：MkDocs + Material
• 主要内容目录：docs/
• 脚本与钩子：hooks/
• 配置入口：mkdocs.yml、pyproject.toml、.pre-commit-config.yaml

开发与验证命令

优先使用仓库内 Makefile 命令：

• make serve：启动本地文档站点
• make format：格式化 Markdown 与 Python
• make format-md：仅格式化 Markdown
• make format-py：仅格式化 Python
• make build：构建站点
• make install-dev：安装开发依赖

如无特殊说明，提交前至少执行：

make format
make build

Commit 规范

建议使用 Conventional Commits：

<type>(<scope>): <subject>

常用 type：

• docs：文档新增/更新
• fix：错误修复
• feat：新能力
• refactor：重构（行为不变）
• chore：维护性调整（配置、依赖、流程）

示例：

• docs(llm): add clip notes and update evaluation
• fix(hooks): handle toc edge cases for empty heading
• chore(ci): adjust upload workflow trigger

约束：

• 一次 commit 聚焦一个主题
• subject 用祈使句、简短明确
• 避免把无关改动混入同一提交

文档格式规范

本仓库以 Markdown 为主，遵循以下约定：

• 标题层级连续，不跳级
• 文件保留清晰一级标题（#）
• 代码块显式声明语言（如 bash、python）
• 列表风格同层级保持一致
• 内部链接优先相对路径，外部链接使用完整 URL
• 新增术语时建议首次给出中英文对照

格式化与检查由 pre-commit 执行：

• markdownlint-cli2（含 fix）
• autocorrect（含 fix）
• ruff / pyrefly（仅 hooks/ Python）

笔记分类

• 文档内容优先放在 docs/ 对应主题目录
  • 每个文件夹下的 index.md 文件用于索引该文件夹下的所有笔记。
  • 根目录的 mkdocs.yml 文件用于配置网站的导航结构与网站设置。
• 自动化逻辑与自定义处理仅放在 hooks/
• 修改站点行为时同步检查 mkdocs.yml
• 仅在必要时调整 CI（.github/workflows/）

docs/
├── AI/ ... AI 相关
├── Math/ ... 数学相关
├── Robotics/ ... 机器人学相关
├── CS/ ... 计算机科学相关
├── Class/ ... 课程相关 (英语、金融、物理、法律、ITP、其他)

Agent 执行原则

• 先最小改动，再逐步扩展
• 不回滚用户已有未请求改动
• 遇到不确定行为先读取上下文文件再修改
• 更新笔记后需要更新 index.md 文件和 mkdocs.yml 文件
• 变更后提供可复现的验证步骤

CLAUDE.md 约定

• CLAUDE.md 作为软连接，指向本文件 AGENTS.md
• 若更新规范，请仅修改 AGENTS.md，避免双份维护