新站首版记录

yiming-next 是这个站点从 WordPress 迁出后的新工程。技术栈是 Astro 5 + Node.js SSR standalone，内容全部以文件形式存储在 content/ 目录下，没有数据库。

内容层

所有内容都是 Markdown（YAML frontmatter）、JSON 或 YAML 文件：

• 文章（content/posts/*.md）：标题、slug、日期、摘要、可见性（public/private/password_protected）、分类、标签、封面图、原始 WordPress URL 等字段。
• 页面（content/pages/*.md）：关于、物品、知识笔记、ChIP 记录表、Agent Fox 对话页等独立页面，同样支持可见性控制。
• 音乐（content/music/playlist.json）：全局播放器的曲目元数据，包含音频 URL、封面、歌词和来源页面。
• 画廊（content/galleries/*.json）：Envira 风格图片画廊，用于摄影等视觉内容。
• 分类/标签（content/taxonomy/）：从 WordPress 导出的术语清单，支撑分类和标签归档。
• 评论（content/interaction/comments/）：每篇文章的评论以 JSON 文件存储，含嵌套回复树。

内容加载走 src/lib/content/load.ts，按可见性区分公开和认证两条路径。Markdown 渲染管线（src/lib/content/render.ts）依次处理：旧站功能标记转换、WordPress HTML 块提取、GFM 渲染、目录生成、HTML 清洗、LaTeX 数学公式、Mermaid 序列图、旧站日记卡片布局、Google Docs HTML 标准化。

页面路由

URL 方案保留了 WordPress 的查询参数习惯（/?p=、/?page_id=、/?cat=、/?tag=、/?m=、/?s=），所有入口收敛到 index.astro 做分发。同时也有语义路径：

• /posts/ 文章列表，/posts/[slug]/ 文章单页
• /archive/ 和 /archive/[year]/ 年份归档
• /categories/[slug]/ 和 /tags/[slug]/ 分类/标签归档
• /search/ 站内搜索
• /about/ 关于页面
• /feed.xml、/sitemap.xml、/search-index.json 公开数据接口

[...legacy].astro 作为兜底路由，通过 URL 清单（content/migration/url-inventory.yaml）解析未知路径，执行 301 重定向或返回 404。

全局运行时

前端运行时（src/components/runtime/SiteRuntime.astro）维护了一个粘性迷你栏，包含：

• 全局音乐播放器：Audio 元素在页面导航中保持不中断，状态通过 localStorage 持久化，支持进度、音量、播放模式控制。
• 浮动工具栏：AI 聊天触发、目录切换、返回顶部、跳转评论区。
• 阅读进度条：页面顶部细线指示当前位置。
• 文章目录：自动从标题生成可折叠导航，IntersectionObserver 高亮当前章节。
• 主题切换：亮色/暗色模式，通过 CSS 变量驱动全局配色。
• 访问者弹幕：页面左下角实时显示最近访客（IP 哈希脱敏），每 10 秒轮询。

运行时兼容旧站 window.wpMusicPlayer、window.lafc_ajax 等全局 API。

Agent Fox AI 助手

Agent Fox（src/components/agent/AgentFox.astro）通过 /api/agent/stream 提供 SSE 流式 AI 对话。关键设计点：

• 双模式：访客看到公开内容检索，管理员（通过 cookie 认证）获得完整站点上下文和 owner 人格。
• 工具集：keyword_search、semantic_search、get_post_chunk、comment_query、search_media、analyze_image、recommend_content 等。
• 速率限制：60 秒窗口内 12 次请求。
• 数据回调：/api/agent/data/[kind] 和 /api/agent/data/[...path]，提供文章列表、批量内容、分类、媒体元数据等 JSON 接口。
• 旧站兼容：/wp-json/agent-fox/v1/stream 和 /wp-json/agent-fox/v1/data 通过中间件路由到同一后端。

评论系统

评论提交端点 /wp-comments-post.php 保持活跃，兼容旧站前端表单。提交时需通过算术验证码（HMAC 签名）。评论存储在 content/interaction/comments/posts/ 下，支持嵌套回复和树形渲染。WordPress REST API 评论路由和 Akismet 端点已返回 410。

旧站兼容层

中间件（src/middleware.ts）在每次请求时处理认证、旧站 API 路由、插件静态资源拦截和访问者追踪。保留的 WordPress 兼容接口包括：

• /wp-admin/admin-ajax.php：处理 10 余个 legacy action（记忆墙、AI 相关文章、媒体搜索等）。
• /wp-content/fonts/：旧站字体文件。
• URL 合约系统（src/lib/url-contract/）：URL 清单追踪每条旧站链接的处置决策（保留、重定向、丢弃、私有化），配合 Redirection 插件导出规则实现 1:1 的 URL 兼容。

其他模块

• OSS 图片代理：/api/media/oss-image 代理阿里云 OSS 图片，设置防盗链 referer，附加长期缓存头。
• 隐私策略（src/lib/privacy/policy.ts）：可见性过滤 + 文本替换规则，对公开渲染和 AI 数据回调生效。
• 向量索引：独立的向量服务用于 Agent Fox 语义搜索，站点侧生成同步请求 payload。
• 迁移工具：src/lib/migration/wordpress-import.ts 支持从 WordPress JSON 导出文件加载文章、页面和元数据，自动扫描旧站 shortcode 并生成功能清单。
• 系统状态：/api/health 健康检查端点，供外部监控和部署验证。

内容契约

所有内容类型的 frontmatter 字段、类型、校验规则和 URL 生成逻辑见 docs/06-content-contract.md。新文章只需在 content/posts/ 下新建 .md 文件，按契约填写 frontmatter 即可。