跳到主要内容

仓库结构

仓库是 Docusaurus 个人知识站点。本文件覆盖目录结构、构建命令、提交规范、静态资源原则。

目录结构​

  • docs/：站点主体内容，按编号分组为 01-网络安全/、02-人生系统/、05-吴飞飞/；人工智能相关内容统一位于 docs/01-网络安全/02-人工智能安全/，其中 01-智能工程/ 是 AI 安全的基础层。人生系统下包含健康幸福、事业有成、财务自由、人生丰富四个目标，其中带 SKILL 徽标的文档是给 AI 协作助手使用的工作规则文件，统一放在 关于FEEI.CN/ 子目录中。
  • docs/01-网络安全/02-人工智能安全/：按 01-智能工程/、02-AI系统安全/、03-AI赋能安全/、04-AI滥用防御/ 组织内容；通用 AI 原理、使用实践、组织转型和项目实践放在智能工程基础层，三条安全主线通过链接交叉引用。
  • blog/：博客文章。
  • static/：静态资源根目录。站点图标、PDF、音乐、媒体、结构化数据按子目录分开。
  • static/data/：结构化数据目录，例如 static/data/reading/、static/data/health/、static/data/maps/、static/data/account-assets/、static/data/hk-ipo/、static/data/llm-usage/。
  • static/media/文章目录/：文档正文引用的大体积媒体资源，例如 static/media/annual-review-for-2025/；文档使用 /media/annual-review-for-2025/example.webp 这类路径引用，由 rsync 同步，不进入 Git。文章目录名应尽量全站唯一，避免使用泛泛的 assets/ 作为顶层目录。
  • src/theme/：Docusaurus 主题覆盖和 React 自定义组件。
  • plugins/：本地 Docusaurus 插件。
  • build/、.docusaurus/：Docusaurus 生成产物。不要手动编辑——下次构建会被覆盖。

构建、检查与开发命令​

  • npm run start：启动本地开发服务器。
  • npm run build：生成生产构建到 build/。
  • npm run serve：本地预览构建产物。
  • npm run typecheck：执行 TypeScript 类型检查。
  • npm run check:docs：检查工作区新增或修改的 Markdown/MDX；错误会阻止继续发布。
  • npm run audit:docs：审计全量文档；存量迁移项以 warning 输出，不因历史债务失败。
  • node scripts/test_ai_navigation.mjs：检查人工智能安全与智能工程目录、导航和相关 Markdown 文件链接；通过 AI_MIGRATION_BASE 指定完整基线提交 SHA，可额外验证迁移前后的文章、slug、首次发布日期与演讲快照。
  • npm run clear：清理 Docusaurus 缓存，适用于路由或主题异常。
  • Node.js >=20，以 package.json 为准。

修改文档后先运行 npm run check:docs。仅在 git push 前必须执行 build 验证：

npm run build 2>&1 | grep -E "WARNING|SUCCESS|ERROR"

输出必须是 [SUCCESS] 且无 [WARNING]，否则不能推送。

静态资源与外部依赖​

站点自身依赖的稳定资源优先放到 static/ 本地目录，用户内容和自动沉淀的数据可以保留原始外部 URL。

  • 新增站点图标/字体等基础资源 → 放到 static/media/ 下对应目录，组件用 /media/img/... 等相对路径引用。
  • 新增 JSON 等结构化数据 → 可放到 static/data/ 下对应目录，组件用 /data/... 路径引用。
  • 新增文档正文图片/视频/音频等大体积媒体 → 可放到 static/media/文章目录/，文档用 /media/文章目录/文件名 引用；如果来源本身是可信外链，也可以保留外链。
  • 日记、Issue 沉淀、抓取类内容中的 GitHub attachment、CDN 图片等 → 默认保留原始 URL，除非明确要求本地化或长期可用性很重要。
  • 第三方 npm 包内置资源 → 通过 Docusaurus 标准 import 链入，不直接写绝对 URL。
  • 微信读书等抓取类资源（封面、JSON 元数据）→ 可继续使用本地 static/data/reading/books/<bookId>/... 路径，也可按数据源实际情况保留远程 URL。

提交与合并请求​

提交信息使用中文，风格以简短祈使句为主，例如：添加站点图标、重构健康文档并恢复更新时间、优化财富框架。一次提交只聚焦一类改动。

不要在 commit 信息中添加 Co-Authored-By 行。

PR 建议至少包含：

  • 本次改动摘要
  • 受影响的目录或页面
  • 可见界面改动的截图
  • npm run typecheck 与 npm run build 通过说明