Docusaurus 配置

Docusaurus 配置相关规则。

文章与分组目录规则

本节规定文章和分组目录的文件位置，页面职责、内容结构与验收使用 我的写作原则。

• 单篇文章直接放在所属目录下：如果一个目录只有一篇 Markdown/MDX，且没有子目录，它就是文件组织层，不应再套一层目录和 index.md。例如“为什么我要分享自己的经验”应直接写成 03-为什么我要分享自己的经验.md。
• 有多篇内容的主题才保留目录：目录有多个子页面时，可以保留目录内的 index.md 作为主题总览；它的职责是导读、关系说明和阅读路径，而不是给单篇文章占位。
• 有子目录的分组可以保留入口页：入口页放在分组目录内部，并使用目录名命名，例如 04-AI应用与组织/04-AI应用与组织.md。
• 移动文章时保持 slug：文件路径变化不应改变已发布 URL；同步修复代码导入、相对链接和生成脚本中的路径。

不要为了形式上的层级，把单篇文章包装成“同名目录 + index.md”。

侧边栏

sidebars.ts 主要使用基于目录结构的自动侧边栏，因此移动文档会直接影响导航。网络空间安全与人工智能安全分别使用独立侧边栏。智能工程作为做好 AI 安全的基础层，放在 docs/01-网络安全/02-人工智能安全/01-智能工程/，随 aiSecuritySidebar 一起生成导航，不再设置独立顶栏或侧边栏。人生系统按目标组织内容。

人工智能安全按“一个基础层 + 三条安全主线”组织：智能工程、AI 系统安全、AI 赋能安全、AI 滥用防御。文章以主要问题决定目录，演讲、教程等形式使用元数据区分，不复制正文。迁移需保留既有 slug、首次发布日期与演讲快照，并同步修复相对链接；运行 node scripts/test_ai_navigation.mjs 检查导航与文件链接。

全站配置

全站级配置应放在 docusaurus.config.ts，不要散落到各文件。

新文章 RSS

homeRecordsPlugin 从公开文档生成 /rss.xml，收录填写 published_at 的 article、tutorial、review、essay，排除草稿、未列出页面及 SKILL。按首次发布日期倒序保留最近 100 篇，条目标识使用稳定原文地址；正文修改不会重复产生新条目。无效或未来日期不收录，未来日期不会自动发布，需在日期到达后重新构建部署。

推送 main 的文档变更会触发网站构建与部署，RSS 随构建更新。自动内容工作流成功结束后通过 workflow_run 触发部署，避免 GITHUB_TOKEN 推送不触发其他工作流的问题；也可手动运行 Deploy website。阅读器按自身抓取周期发现新文章，不保证即时通知。工作流配置需先合入默认分支才生效。

近期更新与更新时间

首页网络安全近期更新读取 doc-mtime-plugin 的 updatedAt，按 Git 更新时间倒序排列，显示北京时间日期。文章操作菜单共用同一份 Git 元数据；未知更新时间不使用文件检出时间补齐。首次发布日期继续独立用于 RSS，不因正文修改而更新。

缓存异常

路由或主题异常时，运行 npm run clear 清理 Docusaurus 缓存。