个人 AI 知识站建设

专题说明

这个专题记录从空仓库到个人内容站的演进过程，覆盖信息架构、内容模型、UI 设计系统、部署、Agent 工作流和后续 AI 检索。它不是一份完成态的文档，而是一条持续延伸的决策路径——每一阶段做完都会回头补一篇复盘，把“为什么这么做”和“当时考虑过哪些替代方案”都写下来。

为什么要把建站过程做成专题而不是单篇文章？因为个人内容站的真正价值不在第一版页面，而在它能不能长期演进。骨架错了，第二阶段就要推倒重来；契约层没设计好，CMS 接入时就要重写一半代码。把这些决策点串起来，后面的人（包括未来的我自己）才能在不重读所有代码的前提下，快速理解这个站为什么是现在这个样子。

当前阶段

第一阶段先完成可演进平台骨架：八类内容集合定型、路由与多语言预留、主题与设计系统、Docker 静态部署、Agent 工作流约束。这一阶段的核心是把规则固定下来，而不是把视觉做到极致——规则对了，后续每个模块都能在同一套约束里扩展。

第二阶段再补细分体验和搜索发现能力：播客详情增强、知识库目录聚合、专题串联、搜索过滤、CMS 写侧接入、AI 向量检索。这一阶段的核心是在不破坏骨架的前提下做加法，每一项新增能力都要先确认它落在哪条已有规则里，而不是另起一套。

为什么选 Astro 作为底座

选型时我对比过 Next.js、Astro、VitePress 三个方向。Next.js 适合做应用，但个人内容站不需要那么多客户端 hydration；VitePress 适合做文档，但内容集合和多媒体承载能力弱；Astro 静态优先、SEO 友好、Content Collections 提供构建期类型安全、岛屿架构让 React 只用于真正需要交互的地方，这套组合最贴合“长期可演进的个人内容站”这个目标。

这个专题后续会补什么

• CMS 写侧接入的完整复盘：从 Payload CMS 选型到契约层设计到发布 webhook 的安全约束，每一环都附上踩坑记录。
• 搜索与 AI 检索的分层设计：Pagefind 静态搜索作为基础层，向量检索作为语义层，两层如何分工、如何共享索引。
• 多语言从预留到落地的迁移路径：/en 路由目前只做预留，真正落地时如何处理翻译同步、hreflang、Sitemap 分语言版本。

维度	第一阶段底座	第二阶段演进
核心目标	可演进平台骨架	细分体验与发现能力
内容模型	八类内容集合定型	CMS 写侧接入契约层
交互能力	主题切换静态优先	搜索过滤与 AI 检索
部署形态	Docker 静态服务	前后台分离对象存储
维护方式	Git 内 Markdown	CMS 草稿预览发布

1. 先读《个人 AI 知识站的第一阶段底座》，理解为什么先固定内容集合、路由、多语言预留和部署，而不是先做视觉。
2. 再读知识库《内容平台架构》，看读侧写侧分离、契约层、结构化 Block 这些关键决策的完整推演。
3. 最后听播客《Agent 内容平台对谈》，理解把 Agent 规范写进建站流程的取舍——为什么不让 Astro 运行时直接执行系统命令。
4. 想看具体组件实现时，再读《用 Astro + MDX 构建可维护的文档组件系统》，了解 Callout、Steps、StatGrid 等组件的设计取舍。

Astro 不是不适合做内容平台，它只是不适合单独承担整个动态平台。把读侧和写侧分开，两边都用最合适的工具，才是长期可维护的方向。