快速参考

高频命令一览。完整目标见 Makefile 指南，完整脚本见 package.json。

开发与构建¶

make dev                  # Cloudflare Tunnel 开发环境（推荐）
make server               # Hugo 服务器（1313）
make build                # 生产构建（= npm run site:build:production）
make build-preview        # 预览构建（drafts/future）
make deploy-preview       # Cloudflare Pages 预览部署
make stop                 # 停所有服务

图片尺寸与上传¶

npm run content:images:check            # 检查图片尺寸完整性
npm run content:images:add-dimensions   # 批量补宽高
npm run content:images:monitor          # 监控处理进度
npm run content:images:upload           # 上传图片
make upload-images                      # 上传到 CDN（Makefile 入口）

正确的图片格式¶

![图片描述](image.webp)
{width=1000 height=467}

尺寸属性独占一行（{width=… height=…}），不要贴在图片语法同一行。

Mermaid 图¶

make mermaid                              # Mermaid 转 SVG
npm run content:mermaid:transform         # 转换入口

详见 Mermaid 转 SVG。

RAG Worker（向量检索）¶

make rag-upload FILE=path/to/file.md      # 单文件向量化
make rag-upload-dir DIR=content/zh/blog   # 递归目录
make rag-reindex                          # 重建索引
make rag-verify                           # 校验
make rag-deploy                           # 部署 Worker
make rag-test                             # 测试

实时日志：cd tools/rag-worker && wrangler tail --format pretty。详见 RAG Worker 总览与向量问题排查。

AI 资源¶

make sync-ai-tags            # 中文标签 → 英文同步
make sync-ai-oss-rank        # 同步 AI OSS Rank
npm run ai:manifest:generate # 生成项目清单

PDF 导出¶

make pdf BOOK=content/zh/book/<book-name>

微信发布¶

make wechat-publish         # 发布到公众号
make wechat-publish-ai      # 发布 AI 内容

文档维护¶

make docs                   # MkDocs 文档服务器
make validate-docs          # 结构校验（npm run docs:validate）
make docs-health            # 健康检查
make docs-freshness         # 新鲜度检查

校验与测试¶

make check-deps             # 依赖检查
make check-built-links      # 构建产物链接校验
make test                   # 测试套件
make test-fast              # 快速测试
npm run link:check          # 链接检查
npm run content:quality     # 内容质量检查

内容元数据¶

npm run content:metadata:update-lastmod   # 更新 lastmod
npm run content:metadata:add-slugs        # 补 slug
npm run content:frontmatter:validate      # 校验 frontmatter
npm run content:seo                       # SEO 检查