CodexGuide 产品需求文档 (PRD)
版本：v1.1.0 (已完成 Spike 验证与架构剪枝)
状态：已冻结（Ready for Implementation）
所属组织与仓库：hyai-dev/codexguide(Private)
对标标杆：CodexGuide.ai Recipes
底层工具链：hyai-dev/site-factory-tools
1. 项目定位与核心愿景
1.1 项目定位
CodexGuide 是面向智能代码 Agent（OpenAI Codex、Google Antigravity、Claude Code、Cursor 等）的下一代实战配方指南库 (Cookbook & Practical Recipes)。
对标站 codexguide.ai 的核心吸引力不是传统 API 文档，而是 “具象工具 × 真实业务痛点 = 立即可用的可复制交付产物”。本项目旨在复刻并超越其内容深度，打造中文技术生态中最敏捷、最高效的 AI 研发落地阵地。
1.2 核心价值主张 (Value Proposition)
- 即粘即跑 (Copy-Paste Ready)：告别泛泛而谈，每篇配方均提供经过严格真机实测的完整配置（JSON/TOML）与一字不差的黄金 Prompt。
- 拒绝 AI Slop 视觉疲劳 (Anti-AI Slop)：严格遵循 Google DESIGN.md 视觉规范，彻底杜绝纯黑
#000000高眩光配色与平庸界面。 - 全链路自动化闭环：借助
site-factory-tools，实现“提交即构建、新篇即收录、报错即通知飞书、域名与邮箱零维护托管”。
2. Spike 技术验证结论与架构决策 (ADR)
为确保 PRD 绝不沦为纸上谈兵，项目组完成了 4 组实测 Spike：
2.1 Spike 成果矩阵
| Spike 项目 | 实测方案 | 验证指标 | 实测结论与决策 |
|---|---|---|---|
| Spike-1：构建框架选型 | VitePress vs Astro Starlight | Node 26 兼容性、冷构建速度、本地离线全文搜索 | 选定 VitePress。实测构建耗时仅 1.8s，无需外挂 Algolia 密钥，内置 MiniSearch 本地毫秒级全文分词；Vue 生态组件自定义最顺手。 |
| Spike-2：设计规范与质量审计 | site-factory design:init 与 design:audit | DESIGN.md 契约生成与源码静态扫描 | 完全打通。成功生成标准视觉契约，对代码块、tabular-nums 及触控动效进行自动化合规审查。 |
| Spike-3：零后端飞书卡片中枢 | Cloudflare Pages Functions + 飞书 Webhook | 无需自建后端服务器下的安全性与交互性 | 完全可行。利用 Cloudflare Edge Serverless 保护飞书 Webhook 密钥，读者反馈与商务咨询直接生成富文本行动卡片推送到群。 |
| Spike-4：架构防过度设计与剪枝 | 业务边界审查 | 维护成本与初期开发 ROI | 完成 4 项关键剪枝（详见第 3 节）。 |
3. 已剔除的不合理设计清单 (Pruned Features)
通过 Spike 验证，为避免初期陷入“伪需求泥潭”和沉重运维成本，以下 4 项设计在当前阶段予以坚决删除：
❌ 剪枝 1：自建独立用户中心、登录系统与 PostgreSQL/Supabase 数据库
- 剔除原因：教程与配方库的第一生命线是极低阅读摩擦力与搜索引擎全域收录。强制登录或复杂会员鉴权会导致跳出率激增 70% 以上，且引入数据库常驻备份与运维开销。
- 替代方案：全站内容保持 100% 开放静态化，极致优化首屏加载与 SEO。
❌ 剪枝 2：自建云端 WebAssembly / 容器级在线代码运行沙盒
- 剔除原因：Codex / Agent 的杀手级案例（如控制安卓手机、连接 Figma MCP、飞书 CLI、Playwright 操控本地浏览器）强依赖本地操作系统权限、私有 Token 与宿主机环境，无法在浏览器公共沙盒中真实落地，投入产出比极低。
- 替代方案：提供标准的前置环境安装命令、一键复现脚手架、真实执行录屏动图以及 GitHub 示例代码仓库。
❌ 剪枝 3：自建复杂的工单后台与审批管理系统
- 剔除原因：独立维护者的时间极其宝贵，自建一套 Admin 后台查看反馈是低效重负。
- 替代方案：通过轻量 Edge Function 将所有读者反馈与失效报错直接推送到维护者的飞书群，生成带【一键前往 GitHub PR / 邮件回复】的交互式行动卡片。
❌ 剪枝 4：纯黑 #000000 高对比度暗黑界面
- 剔除原因：高反差纯黑底色在长时间阅读技术代码和文本时极易造成视觉眩光和睫状肌疲劳。
- 替代方案：严格执行
DESIGN.md，暗色模式采用温和深灰阶（#18181B/#0F172A）结合淡发光卡片描边。
4. 信息架构与内容板块矩阵
┌───────────────────────────┐
│ CodexGuide 站点结构 │
└─────────────┬─────────────┘
│
┌────────────────────┬───────────────┴───────────────┬────────────────────┐
▼ ▼ ▼ ▼
【快速上手 Start】 【工程进阶 Advanced】 【实战配方库 Recipes】 【生态与共建 Community】
01. 什么是 Codex 01. 上下文与费用实操 01. Codex × PPT Skill 01. 社区共建 Roadmap
02. 客户端下载安装 02. AGENTS.md 标准架构 02. Codex × Draw.io 02. 赞助商矩阵与权益
03. 账号与API配置 03. Skills & MCP 扩展 03. Codex × Playwright 03. 配方失效报错通道
04. 第一个任务闭环 04. 沙盒、权限与审批 04. Codex × 飞书自动化 04. 社区配方投稿指南
05. CLI与IDE接入 05. 核心排障与配置手册 ... (持续高频拓展)4.1 单篇实战配方 (Recipe) 的“六步黄金交付规范”
每篇收录的配方必须严格按照以下统一标准撰写，拒绝残缺内容：
- 场景价值与交付产物预览：清晰展示本篇解决的高频痛点，并附上效果动图或高清截图。
- 前置环境与依赖清单：列出所需客户端版本、MCP 插件服务、相关 API 权限。
- 标准配置文件代码块：提供开箱即用的 JSON / TOML 配置片段，支持一键复制代码。
- 黄金 Prompt 指令流：经过实际调优验证的 Prompt 模版，读者只需替换变量即可得到预期结果。
- 排障与避坑提示：明确标注常见阻断报错（如上下文溢出、超时处理、沙盒权限拒绝）及应对方式。
- 产物下载与示例仓库：提供最终代码文件或一键安装命令。
5. 功能特性与交互规范
| 功能编号 | 模块名称 | 核心交互与验收标准 |
|---|---|---|
| F-01 | 本地离线毫秒级搜索 | 基于 MiniSearch 的本地实时中文分词搜索，输入即搜，无需外网依赖，快捷键 Cmd/Ctrl + K 唤醒。 |
| F-02 | Bento Grid 案例展厅 | 首页与实战案例采用 Bento Grid 卡片布局，支持分类标签（#MCP、#提效、#开发）与难度等级标识（🟢 5分钟上手 / 🟡 进阶 / 🔴 深度）。 |
| F-03 | 微动效一键复制 | 所有 Prompt 与配置文件代码块配备触控悬浮复制按钮，带有 active:scale-[0.98] 触控回弹与复制成功浮层提示。 |
| F-04 | 无眩光双主题配色 | 亮色模式清爽自然，暗色模式采用温和深灰阶，严格禁止 #000000 纯深黑反模式。 |
| F-05 | 零后端读者反馈组件 | 每篇配方底部配备轻量反馈按钮（“运行成功” / “报错失效”），通过 Edge Function 直达飞书群行动卡片。 |
| F-06 | 商务赞助与品牌墙 | 赞助商 Logo 阵列、席位权益展示以及一键邮件咨询入口。 |
6. site-factory-tools 工业化全流程联动
本项目与维护者现有的 hyai-dev/site-factory-tools 深度协同：
【CodexGuide 自动化流水线】
│
[1. 规范约束] ──────────► site-factory design:init (DESIGN.md 契约注入)
│
[2. 代码扫描] ──────────► site-factory design:audit (UI 代码质量 100 分审计)
│
[3. 极速发布] ──────────► site-factory cf:pages (Cloudflare Pages + 自动 Spaceship NS)
│
[4. 运营邮箱] ──────────► site-factory cf:email (全站 Catch-all 邮件转发至 Gmail)
│
[5. 极速收录] ──────────► site-factory seo:indexnow (Bing/Yandex 极速广播)
│
[6. 行动中枢] ──────────► Pages Function + notify (读者反馈/赞助直通飞书交互卡片)7. 交付里程碑 (Milestones)
- 阶段一 (M1 - 脚手架与核心基座搭建)：
- 初始化 VitePress 核心工程；
- 导入 Google DESIGN.md 视觉规范与 CSS 主题变量；
- 跑通
site-factory design:audit达到 100 分合规。
- 阶段二 (M2 - 内容骨架与首批核心配方)：
- 构建“快速上手 (Start)”与“进阶工程 (Advanced)”核心文档；
- 重点打磨首批 3 篇重磅实战案例（Codex × PPT、Codex × Draw.io、Codex × Playwright）。
- 阶段三 (M3 - 自动化上线与运营中枢)：
- 接入 Cloudflare Pages 构建流水线；
- 配置
cf:pages自定义域名与全站邮箱 Catch-all； - 部署反馈推送 Edge Function 并配置 IndexNow 极速收录。