AGENTS.md — AI 智能体开发与协作作业规范
本文档是为所有参与本项目的 AI 编码智能体（Antigravity、Claude Code、Cursor Composer、OpenAI Codex 等）制定的行动协议与执行 SOP。
智能体在执行任何代码修改或内容撰写前，必须严格阅读并遵循本文档的所有约束。
1. 单一真实事实来源 (Single Sources of Truth)
智能体在行动前，必须先对齐以下两份规范文件，不得擅自臆造规范：
- 产品与功能需求：
docs/PRD.md - 前端视觉与代码规范：
DESIGN.md
2. 核心架构与目录规范
本项目采用 VitePress 静态站点引擎。所有文档与内容严格按照以下结构组织：
.
├── .vitepress/ # VitePress 核心配置与主题
│ ├── config.mjs # 站点配置、导航与侧边栏
│ └── theme/ # 自定义样式与组件 (遵循 DESIGN.md)
├── docs/ # 文档源码根目录
│ ├── start/ # 快速上手板块 (01-what-is-codex.md 等)
│ ├── advanced/ # 进阶工程板块 (01-cost-context.md 等)
│ ├── recipes/ # 实战配方库 (01-ppt-skill.md 等)
│ │ └── _template.md # 案例标准化模版 (严禁随意篡改结构)
│ └── community/ # 社区共建、赞助商与反馈
├── functions/ # Cloudflare Pages Functions (Edge Serverless)
│ └── api/ # 飞书卡片行动推送等轻量无状态接口
├── AGENTS.md # 智能体作业规范 (本文档)
├── DESIGN.md # 视觉规范契约
└── package.json # 依赖与脚本3. 实战配方 (Recipe) 编写 SOP
当用户要求 AI “编写/新增一篇 实战案例（Recipe）”时，智能体必须严格执行以下流程：
第一步：读取模板
- 读取并复制
docs/recipes/_template.md的标准骨架。
第二步：六步黄金交付格式（缺一不可）
- 元数据 (Frontmatter)：必须包含
title、description、tags（如['#MCP', '#办公提效']）、difficulty（beginner/intermediate/advanced）与estimatedTime（如5 分钟）。 - 场景价值与预期产物：清晰阐述痛点，配以具体交付结果预览。
- 前置准备：列出依赖工具、环境与插件安装命令。
- 核心配置文件：提供开箱即用的 JSON / TOML 代码块，使用标准语言标记（
json/toml/bash）。 - 黄金 Prompt 指令流：经过实际调优验证的精确 Prompt，读者复制即用。
- 排障与避坑提示：明确指出常见报错、超时问题或权限陷阱。
第三步：数字排版约束
- 所有数值、耗时、版本号必须遵循
DESIGN.md要求，确保使用tabular-nums/ 等宽字体展示。
4. 常用工程命令
智能体在开发时使用以下命令（统一使用 pnpm）：
bash
# 启动本地开发服务 (热重载)
pnpm dev
# 执行生产静态构建
pnpm build
# 本地预览构建产物
pnpm preview5. 质量把关门禁 (Quality Gates)
在向用户汇报完成或提交 Git Commit 前，智能体必须在后台自主完成以下两步验证：
门禁 1：构建验证
bash
pnpm build- 必须确保 0 语法报错、0 坏链 (Broken Links)。
门禁 2：UI 质量审计 (site-factory-tools)
bash
node /Users/kfcv50/Github/site-factory-tools/bin/site-factory.js design:audit .- 审查指标：
- 杜绝纯黑
#000000样式反模式； - 核心数值必须包含
tabular-nums； - 交互按钮必须具备
active:scale-[0.98]触控回弹微动效； - Audit 得分必须达到 90 分以上（目标 100 分）。
- 杜绝纯黑
6. 与 site-factory-tools 部署运维联动
当用户要求上线部署、配置域名或推送 SEO 时，智能体调用以下 CLI 工具：
bash
# 1. 一键 Cloudflare Pages 部署与 Spaceship 域名绑定
node /Users/kfcv50/Github/site-factory-tools/bin/site-factory.js cf:pages <domain> \
--repo hyai-dev/codexguide \
--project codexguide \
--branch main \
--email [email protected]
# 2. 一键配置 Catch-all 运营邮箱
node /Users/kfcv50/Github/site-factory-tools/bin/site-factory.js cf:email <domain> \
--forward [email protected]
# 3. 新案例发布后推送 IndexNow 极速收录
node /Users/kfcv50/Github/site-factory-tools/bin/site-factory.js seo:indexnow <domain> \
--urls https://<domain>/recipes/<slug>.html
# 4. Google Search Console 纯 Headless 提交 Sitemap (方案 B)
node /Users/kfcv50/Github/site-factory-tools/bin/site-factory.js gsc:sitemap <domain>
# 5. Google Search Console 实时 URL 收录状态检查
node /Users/kfcv50/Github/site-factory-tools/bin/site-factory.js gsc:inspect https://<domain>/recipes/<slug>.html