技术选型

这篇文章只回答一个问题：这个知识库为什么选择当前技术栈。整体链路看 整体工作流，具体搭建步骤放在 实施步骤，主题和 skill 规则放在 主题和 Skill。

目标约束

这个系统不是博客后台，而是一个长期可维护、AI 可协作的个人知识库。核心约束是：

• 普通内容用 Markdown 就能完成，不要求每篇文章都进入前端开发流程。
• AI agent 能直接读写文件，变更可以被 Git diff 审阅。
• 复杂页面有 MDX、Astro 页面和 raw HTML 作为逃逸口。
• 源码仓库可以私有，但 Vercel 站点是公开的，发布边界必须明确。
• 本地构建、CI 构建和线上部署要尽量一致。

当前架构

Markdown/MDX 内容
  -> Astro + Starlight 构建
  -> GitHub Actions 检查
  -> Vercel 生产部署
  -> chenzeqing.cn 公网访问

仓库是事实源。文章、导航、主题配置、部署脚本都进入 Git；Vercel 只托管构建产物。

Markdown-first

Markdown 是默认格式，因为它最适合个人知识库的长期维护：

• 文件本身就是内容源，不依赖数据库或专有编辑器。
• diff 清晰，方便人和 agent 共同审阅。
• 写作成本低，适合频繁积累。
• 表达能力足够覆盖大多数笔记、复盘、流程和决策记录。

MDX、Astro 页面和 raw HTML 只在 Markdown 表达不够时使用，避免普通文章被表现层复杂度污染。

Astro + Starlight

Astro 负责静态站点生成。知识库大多数内容是静态文本，最终输出成 HTML、CSS 和静态资源，更适合 Vercel 托管，也减少运行时故障面。

Starlight 负责文档站能力：文档路由、侧边栏、搜索、目录、frontmatter schema 和 Markdown/MDX 渲染。新增普通文章时，只要放进对应目录，就能进入文档系统。

Lucode Starlight Theme 负责视觉和主题级组件，让站点不需要自己维护 Header、Sidebar、搜索和目录样式。

GitHub Actions + Vercel

发布链路没有完全依赖 Vercel 的自动 Git 集成，而是在 GitHub Actions 中先执行构建检查，再通过脚本创建 Vercel 生产部署。

保留这层 CI 的原因是：

• npm ci 和 npm run build 能在发布前发现内容、MDX、类型和链接问题。
• Vercel 部署与 Git commit 绑定，线上状态可追踪。
• 部署脚本会等待 Vercel 返回最终状态，失败时能明确暴露在 Actions 里。

隐私边界

私有 GitHub repo 不等于私有网页。只要内容进入 Starlight 构建路径并部署到 Vercel，就会成为公开页面。

当前规则是：

• 可公开沉淀的内容，才放进 src/content/docs/、src/pages/custom/ 或 src/pages/raw-html/。
• token、账号、内部资料、私人信息不写进会发布的页面。
• 部署凭据只放在 GitHub Secrets 或 Vercel 项目配置中。

适用边界

这套技术栈适合静态、可版本化、AI 可编辑的个人知识库。它暂时不处理权限系统、评论、多人实时协作、私密全文搜索或数据库驱动内容。

当前最重要的取舍是：让默认路径足够稳定。写 Markdown，进 Git，过 CI，部署到 Vercel。