Imported from Phil-Fan/Dev-Notes (AGENTS.md). Install upstream with npx skills add Phil-Fan/Dev-Notes. Copyright stays with the author.

AGENTS.md

本文件用于指导 AI Agent 和贡献者在本仓库中协作，重点说明：目录结构、技术栈、以及编辑规范。

1) 项目定位

• 项目名：Phil's Dev Note
• 类型：文档/知识库站点（Fumadocs + Next.js）
• 主要内容：AI、前端、后端、云原生、运维、工具、产品发布与内容相关笔记与资源
• 产品思考 / 产品笔记已迁至个人博客 ~/f/antfu.me/pages/posts/（按产品一篇：poco、zju-charger、token-arena、agentero）

2) 目录结构（以当前仓库为准）

.
├── docs/
│   ├── app/                   # Next.js App Router 页面与布局
│   ├── content/docs/          # Fumadocs Markdown/MDX 文档源
│   │   ├── AI/                # AI 资源
│   │   ├── Backend/           # 后端资源
│   │   │   └── db/            # 数据库资源
│   │   ├── Cloud/             # 云服务资源
│   │   │   ├── container/     # 容器与编排资源
│   │   │   └── runtime/       # 运行时资源
│   │   ├── Frontend/          # 前端资源
│   │   ├── Multiplatform/     # 跨平台资源
│   │   │   └── mobile/        # 移动端资源
│   │   ├── Release/           # 产品发布资源
│   │   │   └── channels/      # 发布渠道资源
│   │   ├── Tools/             # 开发工具与运维资源
│   │   │   ├── dev/           # 原开发工具文档
│   │   │   ├── env/           # 环境配置资源
│   │   │   ├── hardware/      # 硬件资源
│   │   │   └── linux/         # Linux 资源
│   │   ├── CodeQuality.md     # Code Quality 资源
│   │   └── Content.md         # 内容资源
│   ├── lib/source.ts          # Fumadocs 文档源加载器
│   ├── source.config.ts       # Fumadocs MDX 配置
│   ├── mdx-components.tsx     # MDX 组件映射
│   ├── next.config.mjs        # Next.js 配置
│   └── package.json            # 文档站点依赖与脚本
├── package.json               # 仓库级脚本（转发到 docs 子包）
├── pnpm-workspace.yaml
└── .pre-commit-config.yaml    # Markdown 规范检查与自动修复

3) 技术栈规范

硬性约定

• 依赖只加在需要的 package（通常 docs/package.json），保持根精简。

• 新增文档放入 docs/content/docs/，Fumadocs 根据目录自动生成文档树。

• Markdown：一级标题、代码块语言、图片 alt；提交前必须 pnpm lint，导航改动建议 pnpm build。

• Fumadocs 文档树配置位于 docs/lib/source.ts，站点布局配置位于 docs/app/layout.config.tsx。

4) 常用命令

在仓库根目录执行：

pnpm dev      # 启动文档开发服务器
pnpm build    # 构建文档（静态导出到 docs/out/）
pnpm lint     # 执行 pre-commit 全量检查

5) 编辑规范（必须遵守）

5.1 目录文档同步（强制）

更改本仓库目录/文档结构时，必须同步更新下列「目录文件」：

• 文档树中的页面必须对应 docs/content/docs/ 下真实存在的文件。
• 未更新目录文件即视为改动未完成。

5.2 Markdown 规范

• 一级标题：每个文档首行应为 # 标题
• 代码块：必须标注语言（例如 bash、yaml、text）
• 图片：必须提供 alt 文本（避免 ![](...)）
• 避免使用加粗文本代替标题（例如 **标题**）
• 避免重复同级标题名称（必要时加限定词）

5.2.1 告警/提示框语法（Fumadocs Callout）

本仓库使用 Fumadocs <Callout> 组件 作为告警/提示框，禁止使用 ::: 容器、!!! 旧语法或 GFM Alert（> [!TYPE]，当前 MDX 管线不会渲染其样式）。

<Callout type="info">
补充说明、背景信息。
</Callout>

<Callout type="idea">
技巧、最佳实践、快捷操作。
</Callout>

<Callout type="warning">
关键信息、必须了解的内容。
</Callout>

<Callout type="warn">
需要引起注意的警告。
</Callout>

<Callout type="error">
潜在风险、危险操作警告。
</Callout>

<Callout> 与内部 Markdown 内容之间需保留空行；标签必须成对闭合，禁止嵌套空 Callout。

使用 <Callout> 等 JSX 组件的文档必须使用 .mdx 扩展名：fumadocs-mdx 会把 .md 按纯 Markdown 编译，JSX 标签会被静默剥离（内容降级为普通文本）。.mdx 中还需注意：裸 URL 自动链接 <https://...> 要写成 [text](url)；正文中的字面花括号 {} 需转义为 \{\}；HTML 标签必须闭合（如 <br/>）且属性加引号；不支持缩进代码块，须用围栏代码块。

5.3 文件与命名

• 保持现有目录命名风格，不做无必要重命名
• 新文件优先使用小写英文和短横线（与现有结构保持一致）
• 如果是系列文档，可沿用现有编号风格（如 01-File.md）

5.4 提交前质量检查（强制）

pre-commit install                 # 克隆后一次
pnpm lint                          # = pre-commit run --all-files
# 或
pre-commit run --all-files

CI：push / PR 到 main → .github/workflows/check.yml。勿默认 --no-verify。

• 若改动了导航，建议额外：

pnpm build

6) Conventional Commits（必须）

所有提交必须遵循 Conventional Commits：

<type>(<optional-scope>): <short-description>

[optional body]

[optional footer]

推荐 scope：ai、frontend、backend、cloud、ops、tools、pm、awesome、nav、config、deps

示例：

docs(frontend): add react server components notes
docs(ops): update linux networking cheatsheet
fix(nav): correct documentation path for Cloud section
chore(deps): bump fumadocs

约束：

• 一次提交一个主题；摘要用祈使句、小写 type。
• 仅改 Markdown 时用 docs；改 Fumadocs/Next.js 配置可用 chore(config) 或 fix(nav)。

7) Agent 工作约定

• 优先做“最小必要改动”，不要无关重构。
• 不要删除或回滚与当前任务无关的用户改动。
• 若发现目录结构与导航不一致，优先修复为“以文件系统为准”，并做 目录文档同步。
• 修改说明中请明确列出：
  • 改了哪些文件
  • 为什么改
  • 是否已执行 lint/build 验证
  • 是否已更新本文件目录树 / config sidebar